From 8fbd591fd4f2938addffb8bc64790dcb7093d996 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Wed, 24 Feb 2021 13:45:30 +0100 Subject: [PATCH] TechDocs: Update roadmap with milestones --- .github/styles/vocab.txt | 1 + docs/features/techdocs/README.md | 132 +++++++++++++------------------ 2 files changed, 54 insertions(+), 79 deletions(-) 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..cb8d42ec75 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -22,79 +22,20 @@ about TechDocs and the philosophy in its ## Features -- A centralized place to discover and read documentation. +- Discover technical documentation of a service closer to the service page in + Backstage catalog. -- A clear end-to-end docs-like-code solution. +- Create new documentation-only sites for any purpose by just writing Markdown. -- A tightly coupled feedback loop with the developer workflow. (_Coming soon in - V.3_) +- Explore the large ecosystem of + [MkDocs plugins](https://www.mkdocs.org/user-guide/plugins/) to create a rich + reading experience. -- A developer ecosystem for creating extensions. (_Coming soon in V.3_) +- A tightly coupled feedback loop with the developer workflow. (_Future work_) -## Project roadmap +- A developer ecosystem for creating TechDocs widgets. (_Future work_) -| 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 +58,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 docs 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 +114,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).