Amplifying Google's Season of Docs

Google has initiated a Season of Docs collaborative program aimed at improving open source documentation. It provides a great opportunity for us involved in open source and documentation to focus on big communication challenges.

Challenges

• 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 communicate with a range of personas. They have different 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.

This might involve:

• 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.

If we can achieve this:

• Writer contribution impact will be maximised,
• Community writing will become more effective,
• And documentation maintenance will become more sustainable.

Further Reading

The OSGeo Foundation's focus in Season of Docs 2019:

• High impact writing tasks, targeting the greater Open Source community, OSGeoLive, QGIS and GeoNetwork.

General:

• Google Season of Docs
• Inspiring techies to become great writers

Documentation Strategy:

• What nobody tells you about documentation
• Document type definitions I’ve written before.

Research into building open source communities:

• Analysis of over 170,000 open source projects to identify success factors
• Success factors of episodic volunteering in Open Source