Speaker: Mikey Ariel (@ThatDocsLady)
Slides: https://speakerdeck.com/thatdocslady/docs-or-it-didnt-happen
Video: TODO
-
Content strategy:
- Lookup documentarians (Wrtie the Docs).
- Asking the right questions in advance can save a lot of time.
- Document the things that matter:
- Need-to-know docs (you don't need to know anything).
- Five-ws:
- Who are the readers?
- What do they need to know? What do they want to know?
- When do they need to now it?
- Where is / should the information be consumed? Error messages are legit docs!
- Why do they care?
- Document the things that matter:
- Examples:
- Gnome asks who you are and points you to the right place (help.gnome.org)
- Arch Linux wiki, difficult to browse but users are likely to search.
- Minishift README (TODO: gh minishift link), short, points to correct places (acts as a portal).
- Minishift troubleshooting, warning messages link to further info in the docs.
-
DevOps for docs:
- Integrate with development procedures, you already have that tooling.
- Treat docs as code, put your docs in the repo.
- Modularise your content, if you need to scroll more than a couple of
times it's too long! More than 3 or 4 sub-heading is too many.
- It's easier to move and restructure modular content.
- Use ticketing for your docs, just like your code.
- Automatic build and deploy.
- Automate testing of your docs: Hemmingway, Emender
-
Community spirit:
- Make docs a requirement.
- Have contribution guidelines.
- Provide templates.