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.
toggle quoted message
Show quoted text
On 20 May 2019, at 20:11, Michelle Noorali <michelle.noorali@...> wrote:
Thank you Brian. That’s a really good point.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.