vitessio
Umbrella Issue: CNCF Tech Doc Recommendations
☂ Umbrella issue
This is a checklist for the CNCF technical documentation analysis recommendations. It should be updated as sub-issues are added, completed, or otherwise modified.
This issue tracks recommended changes resulting from an analysis of the Vitess documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses/0014-vitess.
The CNCF Vitess documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/issues/280
🗞️ Sub-issues
This is a list of issues representing the recommended work on the Vitess website and technical documentation.
Remove "topo_flags" notification
Remove an erroneous notification on the Global TopoServer page:
- [x] https://github.com/vitessio/website/issues/1970
Write a "Get Started" introduction
The documentation should provide an easy-to-follow onboarding path for new users. Start by writing an introduction on the Get Started landing page.
- [ ] https://github.com/vitessio/website/issues/1971
Write a "What's Next" roadmap
Write a roadmap enabling new users to find instructions that they want.
- [ ] https://github.com/vitessio/website/issues/1972
Clarify "What Is Vitess"
Clarify the beginning of the Overview, the "What is Vitess" page.
- [ ] https://github.com/vitessio/website/issues/1973
Rename tasks
Pages in the User Guide should name the tasks that are described on them. This will vastly improve users' ability to find procedures.
- [ ] https://github.com/vitessio/website/issues/1974
Rewrite tasks
The User Guides should consist primarily of this type of information. It should be a procedure guide.
- [ ] https://github.com/vitessio/website/issues/1979
Reorganize tasks
Reorganize the User Guide by user role. Within roles, organize the tasks around use cases.
- [ ] https://github.com/vitessio/website/issues/1980
Remove the FAQ
Remove the FAQ from the documentation website.
- [ ] https://github.com/vitessio/website/issues/1981
Add a glossary
Add a glossary of terms to the document website.
- [ ] https://github.com/vitessio/website/issues/1982
Consolidate troubleshooting
Consolidate all troubleshooting information into one troubleshooting guide per user guide/user role and move the troubleshooting guides within the versioned technical documentation.
- [ ] https://github.com/vitessio/website/issues/1983
Rename the "Programs" CLI reference library
Make CLI references more findable by renaming the "Programs" reference section.
- [ ] https://github.com/vitessio/website/issues/1984
Explain installation options
Explain all the installation options on the Getting Started page..
- [ ] https://github.com/vitessio/website/issues/1985
Provide technical documentation creation procedures
Create documentation for website and tech doc content creation.
- [ ] https://github.com/vitessio/website/issues/1986
Remove non-inclusive language
- [ ] https://github.com/vitessio/website/issues/1987
Remove non-inclusive language throughout the documentation as recommended by the Inclusive Naming Initiative.
Clean up documentation issues
There are dozens of issues open against the Vitess documentation, going back to 2018. Improve documentation issue handling by cleaning up old issues and implementing procedures.
- [ ] https://github.com/vitessio/website/issues/1988
Here's the Vitess TechDocs Analysis, which may help provide context for this work. Thanks @dwelsch-esi!
Hi @dwelsch-esi. I'd love to hear your thoughts on this.
Based on your Vitess techdocs analysis, I came up with an IA table that reflects the recommendations in the document. I have also added some of my own based on similar projects.
Let me know what you think and how to improve it. If the Vitess team approves, I'd be happy to start implementing the proposed changes :)
| Website | Top Nav | Section | Sub-section |
|---|---|---|---|
| Proposed Vitess Website IA | Home | ||
| Docs | Overview | - What is Vitess | |
| -Architecture | |||
| -Concepts | |||
| -Supported databases | |||
| -Scalability philosophy | |||
| -Cloud native | |||
| -History | |||
| Getting started | -Vitess admin | ||
| -Database Admin | |||
| -Application developer | |||
| Link each role to its User guide | |||
| User guides | -Admin guide | ||
| -Database admin guide | |||
| -Application developer guide | |||
| whats next ->Roadmap | |||
| Troubleshooting | |||
| Reference | - CLI | ||
| - APIs | |||
| Glossary | |||
| Releases | v.23.0 (Development) | ||
| v.22.0 (Stable) | |||
| v.21.0 (Stable) | |||
| v.20.0 (Stable) | |||
| Archives | |||
| Release Cycle | |||
| Release Team | |||
| Release Notes | |||
| Changelog | |||
| Community | Contribute | ||
| Learning Resources | |||
| Blog | |||
| English/Chinese |
@Dindihub I like what you've done here. Some specific features that I think work well:
- The Docs Overview section is well organized as-is.
- Docs Overview and Getting Started are good choices for the first two sections of the documentation.
- I like the idea of putting the Releases section in the top nav menu. That frees up space in the left column table of contents (TOC). Keep in mind that the user should be able to easily tell which version they're looking at while actually in the doc.
I'd suggest the following changes:
- Remove the user guides from the Getting started section. Getting Started should be a path or workflow that leads the user through installation, configuration, and initial test/demo. At the end of that workflow, use a "What's next?" to point them to the user guide(s).
- I'd move Learning resources down the TOC. They don't need to be the third thing in the TOC. Also, they're another thing you can link from "What's next" in the Getting started doc.
- You've got two Glossary entries. One will probably suffice. 😄 Seriously though, I'd give some thought to what TOC entries should follow Getting started, and in what order. Look at some other tech doc websites to get some ideas. I might do something like the following. Keep in mind though that this can vary a lot.
- Overview (with sections as per your table)
- Getting Started (describe the roles on this page, then provide links to the role-based getting started instructions, if they differ)
- User guides (this page can contain the "What's next" roadmap information
- Admin guide
- Database admin guide
- Application developer guide
- Troubleshooting
- Learning/Tutorials
- Reference
- CLIs
- APIs
- Glossary
@Dindihub I like what you've done here. Some specific features that I think work well:
- The Docs Overview section is well organized as-is.
- Docs Overview and Getting Started are good choices for the first two sections of the documentation.
- I like the idea of putting the Releases section in the top nav menu. That frees up space in the left column table of contents (TOC). Keep in mind that the user should be able to easily tell which version they're looking at while actually in the doc.
I'd suggest the following changes:
Remove the user guides from the Getting started section. Getting Started should be a path or workflow that leads the user through installation, configuration, and initial test/demo. At the end of that workflow, use a "What's next?" to point them to the user guide(s).
I'd move Learning resources down the TOC. They don't need to be the third thing in the TOC. Also, they're another thing you can link from "What's next" in the Getting started doc.
You've got two Glossary entries. One will probably suffice. 😄 Seriously though, I'd give some thought to what TOC entries should follow Getting started, and in what order. Look at some other tech doc websites to get some ideas. I might do something like the following. Keep in mind though that this can vary a lot.
Overview (with sections as per your table)
Getting Started (describe the roles on this page, then provide links to the role-based getting started instructions, if they differ)
User guides (this page can contain the "What's next" roadmap information
- Admin guide
- Database admin guide
- Application developer guide
Troubleshooting
Learning/Tutorials
Reference
- CLIs
- APIs
Glossary
Thanks for the feedback @dwelsch-esi. Makes sense to have the user guides in their own section. I've added your suggestions to the table. I think it's a good start and we can add more ideas as we go.
Also, thanks for noticing the Glossary repetition, I meant to keep the one at the bottom. 😊
Hi @dwelsch-esi. I am interested in working on this umbrella issue as a whole-like a project, but I fear it wouldn't make sense until the whole IA is rearranged.
First, I would like to understand if you or CNCF have plans on how to handle these issues, or should I contact the Vitess team for a way forward? I worked on a similar project as a CNCF mentee last year, and I'd love to work on this too. Let me know. Thanks
@Dindihub, CNCF doesn't have plans to handle these issues as far as I know. @nate-double-u can give you more information about their involvement, but in general they're delighted to have contributors take on doc project issues. If you take on the whole project I'd talk to Nate about strategies for how to work through the issues with minimal disruption to the existing Vitess user base. I'm happy to meet as well to discuss how to tackle these issues.
Also, if you haven't already, I'd recommend joining the #techdocs channel in the "Cloud Native Computing Foundation" Slack workspace.
@Dindihub, CNCF doesn't have plans to handle these issues as far as I know. @nate-double-u can give you more information about their involvement, but in general they're delighted to have contributors take on doc project issues. If you take on the whole project I'd talk to Nate about strategies for how to work through the issues with minimal disruption to the existing Vitess user base. I'm happy to meet as well to discuss how to tackle these issues.
Also, if you haven't already, I'd recommend joining the #techdocs channel in the "Cloud Native Computing Foundation" Slack workspace.
Good point @dwelsch-esi . Let's move the discussion to Slack.
in general they're delighted to have contributors take on doc project issues.
This is very true! 😊
Good point @dwelsch-esi . Let's move the discussion to Slack.
Honestly, keeping the discussion here on GitHub may be better, especially since you've already had so much discussion here, moving it to slack will fracture the discussion, and folks reading here may not see the resolution or any decisions made.
Glad to have your take on this @nate-double-u. It's okay to have it here for transparency.
I had a meeting with @dwelsch-esi to kickstart the process and map out our roles in the project. Some of the issues that came up that may require guidance from you, @nate-double-u, and @chalin were:
- How to get engineers from Vitess involved in the process, at least one to oversee implementation and share their ideas for the site
- The extent of my contribution. I understand @dwelsch-esi was only doing the analysis and may oversee its implementation, but not the technical bits. I am ready to take on the technical parts like reorganizing the pages as per the analysis, but I may need some guidance.
In the meantime, I will be working on issues that don't affect the current IA. Waiting on @dwelsch-esi to make some great suggestions as we consult on the reorganisation.