the challenge of documentation


Brian Grant
 

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.