Re: the challenge of documentation
Michelle Noorali <michelle.noorali@...>
toggle quoted message Show quoted text
Thank you Brian. That’s a really good point.
On May 20, 2019, at 6:41 PM, Brian Grant via Lists.Cncf.Io <briangrant=google.com@...> wrote:
The challenge of documentation was mischaracterized in the GB/TOC meeting today.It's less that contributors don't want to produce good documentation, but that it requires specialized expertise to do so. Issues like:
- Information architecture
- Navigation hierarchy and SEO to make documents sufficiently discoverable
- What types of documents are needed and what structure and content they should have
- Identifying target audiences and user scenarios that need to be represented in tutorials and how-to documents
- Documentation versioning
- Site management and analytics
- Internationalization and accessibility
- Mobile and web layouts
- Tools and services available for publishing/hosting documentation
- Processes for accepting contributions and keeping technical content up to dateProducing and maintaining documentation is hard.