List of resources for writing documentation

[sypets]

There is already a resources page: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/Resources.html#resources

I would like to collect some more resources here.

Plan documentation writing

• 5 Steps to Create Technical Documentation That’s (Actually) Helpful
• altexsoft: Technical Documentation in Software Development: Types, Best Practices, and Tools

Documentation structure

• What nobody tells you about documentation

These are some questions / classifications:

• target audience by main task e.g. extension developer, core developer, integrator (theme), integrator (configuration) etc.
• target audience by experience level (e.g. beginner (to TYPO3), experienced)
• type of documentation (e.g. reference manual, tutorial, etc.)
  • Explain from the point of view of what is there (e.g. the API in a reference) or a task to be accomplished (e.g. create a theme in a tutorial)
• how to structure the menu(s)

Tips:

• create a (rough) table of contents for entire docs
• create personas and user stories

Other documentation (with good structure)

• PHP Slim Documentation: get started, concepts, start page with "What's the point?", "How does it work"
• Django documentation: start page with "Getting help", "How the documentation is organized", FAQ
• Scrapy FAQ, "Solving specific problems", "Basic Concepts"

Good ideas:

• Put most important stuff and links to most important stuff on the start page (e.g. as a teaser with links to more information)
• most important (most used) things first (on top)
• "New to TYPO3" (instead of "Getting Started"?)
• "Concepts"
• Have an FAQ?
• What can xyz do for you? What's the point?
• "How does it work?"
• "Getting help"
• "Solving specific problems" (aka short "howto guides")
• describe an action "I want to ..."

Writing good content

• “8 Tips for Better Readability” by Roby Collinge

Style Guides

• Microsoft style guide (tip from Martin)

Maintainance and Reviewing

• how to keep documentation up to date?
• how to improve existing documentation (review it). What might be a good workflow?
• how to keep track of what is already up to date / reviewed?

Aspects of reviewing:

in order of importance (roughly)

• technically correct, up to date, adheres to best practices
• didactic : easy to understand. Does it walk the reader through all steps (e.g. for a howto guide)
• helpful is the documentation generally helpful?
• structure and findability: structure of menu, topics easy to find. Linked from start page? SEO. Is the menu consistent throughout the docs so things are easily recognizable (e.g. placement of sitemap)
• formatting: does the formatting make it well readable and skimmable. Is the formatting consistent throughout the docs so similar things are easily recognizable
• language, style (well readable, grammar / spelling ok)
• enough and not too much (should this be documented? Is this something which can be easily looked up in the core? Would documentation be even necessary if the GUI or the API were improved? Should we rather focus on that?

[sypets]

Tip via Slack:

https://opensource.com/article/20/3/documentation