diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index b672405d1a..e60d9b9528 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -56,6 +56,7 @@ Olle Onboarding Patrik Phoen +Platformize Pomaceous Preprarer Protobuf diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index f81f41668d..2fa48f57b0 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -22,79 +22,19 @@ about TechDocs and the philosophy in its ## Features -- A centralized place to discover and read documentation. +- Deploy TechDocs no matter how your software environment is set up. +- Discover your Service's technical documentation from the Service's page in + Backstage Catalog. +- Create documentation-only sites for any purpose by just writing Markdown. +- Explore and take advantage of the large ecosystem of + [MkDocs plugins](https://www.mkdocs.org/user-guide/plugins/) to create a rich + reading experience. +- Search for and find docs (coming soon). +- Highlight text and raise an Issue to create feedback loop to drive quality + documentation (future). +- Contribute to and deploy from a marketplace of TechDocs widgets (future). -- A clear end-to-end docs-like-code solution. - -- A tightly coupled feedback loop with the developer workflow. (_Coming soon in - V.3_) - -- A developer ecosystem for creating extensions. (_Coming soon in V.3_) - -## Project roadmap - -| Version | Description | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [TechDocs V.0 ✅][v0] | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](#techdocs-v0) | -| [TechDocs V.1 ✅][v1] | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](#techdocs-v1) | -| [TechDocs V.2 🔮⌛][v2] | Easy adoption of TechDocs (whatever environment you have) [See V.2 Use Cases.](#techdocs-v2) | -| [TechDocs V.3 🔮⌛][v3] | Build a widget (plugin) framework so that contributors can easily contribute features to TechDocs - that others can use. [See V.3 Use Cases.](#techdocs-v3) | - -[v0]: https://github.com/backstage/backstage/milestone/15 -[v1]: https://github.com/backstage/backstage/milestone/16 -[v2]: https://github.com/backstage/backstage/milestone/22 -[v3]: https://github.com/backstage/backstage/milestone/17 - -## Use Cases - -#### TechDocs V.0 - -- As a user I can navigate to a manually curated docs explore page. -- As a user I can navigate to and read mock documentation that is manually - uploaded by the TechDocs core team. - -#### TechDocs V.1 - -- As a user I can run TechDocs locally and read documentation. -- As a user I can create a docs folder in my entity project and add a reference - in the entity configuration file (of the owning entity) to my documentation. -- Backstage will automatically build my documentation and serve it in TechDocs. -- Documentation will be displayed under the docs tab in the service catalog. -- As a user I can create a docs only repository that will be standalone from any - other service. -- As a user I can choose my own storage solution for the documentation (as - example GCS/AWS/Azure etc) -- As a user I can define my own API to interface my own documentation solution. - -Extra platform stability and compatibility improvements: - -- As a user I can define the metadata generated for my documentation. -- As a user I will be able to browse metadata from within my documentation in - Backstage. - -#### TechDocs V.2 - -We have a TechDocs that works end-to-end. The next step is to make it super easy -for companies to adopt. This involves (something like) the following work items. - -- “Solidify” work and “Mkdocs stabilization” work that has come out of our Q3 - end-to-end work. -- Improve/simplify the get up and running process. -- Introduce new documentation templates. -- Extend the already existing docs-template to have options of different - documentation types. -- Enable companies to choose their own storage (S3 for example). -- Enable companies to choose their own source code hosting provider (GitHub, - GitLab, and so). -- Share how to plug in TechDocs to your own CI. - -#### TechDocs V.3 - -Build a widget (plugin) framework so that contributors can easily contribute -features to TechDocs - that others can use. And, also, so that we can easily -migrate Spotify's existing TechDocs features to open source. - -## Platforms Supported +## Platforms supported See [TechDocs Architecture](architecture.md) to get an overview of where these providers are used. @@ -117,7 +57,47 @@ providers are used. [Reach out to us](#feedback) if you want to request more platforms. -## Tech Stack +## Project roadmap + +### **Ongoing work 🚧** + +**Beta release** - +[Milestone](https://github.com/backstage/backstage/milestone/29) + +- It should be possible and easy to use TechDocs in most environments across + organizations. +- Minimal bugs, better error handling and scalable backend and frontend. +- Documentation Search +- TechDocs Homepage with basic features + +### **Future work 🔮** + +**General Availability (GA) release** - +[Milestone](https://github.com/backstage/backstage/milestone/30) + +- Bugs are rare, TechDocs APIs are stable and scales easily in large + organizations. +- Better integration with + [Scaffolder V2](https://github.com/backstage/backstage/issues/2771) (e.g. easy + to choose and plug documentation template with Software Templates). +- Possible to configure several aspects about TechDocs (e.g. URL, homepage, + theme). + +**Implement Feedback loop** - +[Milestone](https://github.com/backstage/backstage/milestone/31) + +- A feedback loop between documentation reader and writer using TechDocs +- The `+` in `docs-like-code+` experience + +**TechDocs widget framework** + +Platformize TechDocs with a widget framework so that it is easy for TechDocs +contributors to add pieces of functionality and for users to choose which +functionalities they want to adopt. As a pre-requisite, the re-architecture of +TechDocs frontend [RFC](https://github.com/backstage/backstage/issues/3998) +needs to be addressed. + +## Tech stack | Stack | Location | | ----------------------------------------------- | -------------------------------------------------------- | @@ -133,14 +113,7 @@ providers are used. [techdocs/container]: https://github.com/backstage/techdocs-container [techdocs/cli]: https://github.com/backstage/techdocs-cli -## Feedback +## Contact us -We have created a sweet and short TechDocs user survey - -https://docs.google.com/forms/d/e/1FAIpQLSdn5Vn3MQhCdyYRuW8cMzZkMQF0bFxXYN168gZRvESLfJWVVg/viewform - -This is to gather inputs from you (the Backstage community) which will help us -best serve TechDocs adopters and existing users. Your inputs will shape our -roadmap and we will share it in the open. - -For any other general queries, reach out to us in the `#docs-like-code` channel -of our [Discord chatroom](https://github.com/backstage/backstage#community). +Reach out to us in the `#docs-like-code` channel of our +[Discord chatroom](https://github.com/backstage/backstage#community).