Re: the challenge of documentation


Liz Rice
 

Great articulation, thank you Brian. IMO this adds more weight to the argument for hiring another writer to help the projects with these doc challenges. 


On 20 May 2019, at 20:11, Michelle Noorali <michelle.noorali@...> wrote:

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 date
Producing and maintaining documentation is hard.

Join cncf-toc@lists.cncf.io to automatically receive all group messages.