Issues/Problems[]
- "We" (us or others) often write documentation for readers similar to ourselves.
- Much documentation is wasted because it's at the wrong level.
- Early OpenStack docs were aimed at developers - now there's a wider audience.
- Often the knowledge never makes the leap to something that's of use to a wider audience.
- Important question: Who are the readers?
- No equivalent of Karl Fogel's book "Producing OSS" for documentation. No canonical source for knowledge of creating docuemntation.
- Does new documentation require new people? (Other than the "alpha geeks"?)
- Interesting boundary between marketing and others in the organization.
- People confuse Wikipedia with a wiki. Much different format/structures.
- Wikis are like a house with all doors and no windows. Not a good landing place for readers.
- Releases may happen without accompanying documentation.
- Nobody owns a wiki, so nobody is accontable for its delivery/maintenance/quality. More of an issue that it's too easy to do bad docs.
- Getting docs to a point where they're "self-sustaining" is critical. If there isn't documentation there, people won't think (or be motivated) to write more.
- Explaining repeatdly wastes time. Write documentation. "The time you save may be your own."
- Lullabot is a good example of quality documentation. http://www.lullabot.com/
- Bikeshedding in documentation? Oxford comma?
Documentation events[]
- Write The Docs conf in PDX had nearly 200 people (!!)
- Open Help conference (annually)
- Regular documentation days in a community. May take time to get regular events going, and may be hard to sustain activity levels. Important to get different groups participating. Some encouragement (coercion?) may be necessary, especially when people don't keep up the effort.
- STC local chapter events http://www.stc.org/
- Content strategy meetup groups (may blend with UX groups)
What could be done to improve things (ideas, tips, etc.)[]
- Community approach: Documentation isn't always seen as enjoyable, so fewer people willing to work on it. An active community focused on docs would help change that. Once senior members stop "doing it themself" others *may* step up.
- Do-able tasks: Small, easy tasks for new docs contributors. Video explanations on how to update/edit docs. Keep an (up to date!) TODO list.
- Improve the audience: Review documentation to understand who the current documentation is written for, and understand who the audiences coming actually are. Identify the gaps.
- Be OK with docs in different formats/places. Get over your concerns. It's OK for docs to be different places. The challenge is tying it together and making it findable.
- Don't send newbies to a wiki. Too confusing, lack of structure, no guidance, etc.
- Put docuemtnation with code commits. Make it a cultural norm & expectation. May not be perfect having the person doing the pull request doing it, but it's better than nothing. (Or is it?) Have devs make a comment of "doc impact" and ensure that documentation impact is evaluated in code review. Create bugs/issues for tracking documentation updates as code is updated. Just having a dev consider the impact may lead to more documentation.
- Give more acknowledgements for documentation. Make it important, valuable ... even as much as code contributions. Acknowledge. Reward. If you want docs to have equal status in your community, give it equal status (start treating it that way).
- Consider quality. Too low quality and the bar is set too low for future contributions. Too professional and people will be afraid to touch it. Information architecture (findability) may be just as important as page content.
- Create "templates" for finished docs. If there are patterns for documentation in your community (meetings, plugin docs, etc.) ... make patterns/templates/widgets for others to use. Consistency counts. Create expectations about how pages are titled/named (e.g. match software functionality). Helps for browsability in lieu of a larger structure.
- Translations are competitive. Globally, there's a lot of national pride in translating. Translating software tends to be more exciting for people than translating docs. Tag files or otherwise create and use a process so translators know what work needs to be done. Consider having translators work on English docs by having them work on small tasks of improving tech-focused docs (rather than end-user docs).
- Let people write new docs in their preferred language. If foreign writers want to create new content, and they can't write in English, let them even a machine translation into English can be useful as a starting point.
- Separate content from design. Work on docs in GitHub (e.g.) and use lightweight markup. Then make it look nice, useful, etc. on your web site.
- Keep developers engaged in documentation. Some things are so complex, a writer can't do it alone. There's no magic documentation button.
- Commit project leadership.
- Create a global "best practices" (OSS?) documentation mailing list or other communication channel. Eric Holscher will do a lightning talk tomorrow and mailing list will be announced. Jean W. will tell Scott who will inform the entire world. Might be a good place to share templates across projects/organizations.