Adapt the content types, review process, and review checklists for a wider audience.
Work in progress
Guiding questions
- Do content types help people understand how to create good documentation?
- Can a self-service review process help teams improve and maintain their docs?
Inspiration
Terminology
- template: a MediaWiki template. Avoid overloading this term.
- outline: a wikitext document that acts like a skeleton to fill out to create a page following a content type
- review: the process of evaluating and improving a document
- review checklist: a set of questions and list items for completing a review
Content types
Previous work
List of technical documentation genres (2018/2019)
- FAQ
- Walkthroughs, how-tos, and tutorials
- Quickstart guide (QSG)
- User guides, reference guides, and technical manuals
- README
- API Documentation
- Troubleshooting
- Release notes
- White paper
- Technical specification
- Blog post
- Abstract
- Position paper
- Tickets (task, bugs, features request, etc.)
- Conference proposals
- Conference presentations
Work done as a part of KR1
Content types for documentation review process (2021)
- landing page
- cross-collection landing page
- how-to guide
- tutorial
- explanation
- reference doc
Content types in the key doc spreadsheet (2022)
- app
- blog
- code repo
- contributing guide
- explanation
- how-to guide
- landing page
- readme
- tutorial
Lessons learned
- Remove cross-collection landing pages: The distinction between landing pages and cross-collection landing pages was too confusing. Content types should be obvious and easy to understand.
- Add more types: Instead of trying to fit everything into a subtype of one of the Diataxis types, allow for any content type that is sufficiently distinct and easy to understand, such as READMEs and contributing guides.
Review process and checklists
Previous work
Documentation review process (2020)
- Prototype/Self review
- Technical review
- Non-technical review
Work done as part of KR1
Key doc review processes (2021)
- Review checklist - general
- Review checklists by content type
- Review checklist - style
- Basic review checklist
Lessons learned
- One size doesn't fit all: The original review process was very long and time consuming, including both a content audit and style review.
- Phabricator is better for reviews: Given the choice between completing a checklist on a wiki page vs a Phabricator task, using Phabricator was easier, more discoverable, and more collaborative. This is a good example of using Phabricator for temporary information vs persistent knowledge