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.