- Vision: Does everyone know the characteristics of good open source documentation? Does anyone know? Let’s collate research and best practices into accessible guides and templates.
- Targetted: Projects have a range of audiences with differing technical backgrounds, attention spans and information needs. A range of documentation types are needed. Each requires different levels of depth, specificity, currency, narrative, personalisation, examples, and more.
- Empower everyone to contribute: Good documentation benefits from cross-disciplinary contributions: from developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. Open source documentation processes are typically set up by developers, for developers, and have a significant barrier-to-entry for others. How can we fix that?
- Attract volunteers: How can we apply our knowledge of collaborative and volunteer communities to attract documentation teams? How can we help volunteers maximise the impact and effectiveness of their contributions?
- Current and Sustainable: How can we sustainably keep documentation synchronised with rapidly evolving software? How do we help users find current material and archive outdated docs? How do we minimise maintenance?
What to focus on?To maximise value, I suggest promoting initiatives which:
- Use and contribute to documentation best practices.
- Use templates and guides for key documentation types to help cross-domain collaboration.
- Attracts volunteers, from multiple user profiles.
- Applies multi-directional mentoring.
- Refines workflows and tools to reduce barriers-to-entry.
- Focuses on a specific initiative which tests the bounds of these ideas for a specific project and captures lessons learned.
- Auditing existing documentation.
- Defining a writing strategy.
- Developing or refining a specific documentation type for a project.
- Mentoring a project’s community, increasing the initiative's sustainability.
- Contributing to best practices.
- Writer contribution impact will be maximised,
- Community writing will become more effective,
- And documentation maintenance will become more sustainable.
- Analysis of over 170,000 open source projects to identify success factors
- Success factors of episodic volunteering in Open Source