Mixing experienced tech writers with open source communities revealed new approaches for creating better documentation.
 |
| OSGeoLive distribution we've been documenting |
During
OSGeo Foundation’s involvement in
Google Season of Docs, we discovered that, like many open source projects, we knew little about:
- The state of our docs,
- What we were aiming for,
- What our priorities were,
- The details of the challenges we faced, or
- How to improve.
We discovered:
- How hard it is to keep tech docs current,
- Skillsets from multiple roles are needed to create good docs,
- Open source’s docs and writing processes are immature when compared to software development.
It is an exciting problem space with high-value challenges ready to be tackled. It reminds me of the early days of open source before it became trendy with business.
What should tech writers work on?
Open source communities welcomed the chance to have tech writers improve our docs, and expressed a pressing need for it, but found it hard to articulate exactly what needed fixing.
- People explained that their project docs often hadn’t been updated between doc releases.
- Some projects had noticed new features that had not been documented.
- Other projects had issue lists - collating observed deficiencies, but had no systematic review.
- Most observed that docs were created by developers with no formal tech writing training.
- Many noted that their English docs were written by non-native English speakers.
But where should we start? We needed to decide on what we wanted, and what we should work on first.
What’s the definition of good docs?
And then we realised that we didn’t have a good definition of “good documentation”. For our software projects, we have a comprehensive
incubation process to assess the maturity of software and the project’s community, but we couldn’t find a similar set of metrics to define “good documentation”. So we started
TheGoodDocsProject, to collate “best-practice templates and writing instructions for documenting open source software.”
This helped us define what we were aiming for, and prioritise what we can achieve with our available resources.
Documentation audit
Once we knew what good docs looked like, we were then able to audit the status of projects' docs:
- What documentation do we have?
- Does it cover all the functionality?
- Does it cover end-user needs?
- Is the documentation any good?
We discovered that the quality, currency, and completeness of our OSGeo docs were immature when compared to the quality software they described.
It takes a village to raise good docs
In researching open source projects’ documentation needs, it’s become clear that crafting good docs requires multiple skillsets. Ideally, a doc team has access to:
- A developer, with a deep understanding of the software being described.
- A user of the software, able to explain the application within the context of the application’s domain.
- An educator, who understands the principles of learning.
- An information architect, who understands how to structure material.
- A writer, who writes clearly and concisely with good grammar.
- Someone who speaks English as a first language (for English docs).
- A translator, who is good at translating into multiple languages.
- A DevOps person, who can set up doc build pipelines.
- A community builder, facilitator, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas collaborate together.
Technical writers usually have a high-level understanding of most of these domains and their skills are often under-appreciated and under-utilised, especially if directed with a vague “just clean up the grammar and stuff”.
However, the best docs typically have had been influenced by multiple stakeholders. This can be partly achieved
using templates to collaborate between domains, timeframes, job roles, projects and organisations.
Tools for documenting open-source projects are painful
We experienced significant pain in trying to convert between writing and software toolsets. We love the versioning of git, are frustrated by clunky markdown interfaces, and want access to editing and review workflows of
Word and
Google Docs, along with grammar and syntax plugin tools such as
Grammarly. Translation tools such as
Transifex are pretty cool too.
Could someone please write an application which addresses this use case. Maybe there is an idea in here for a future Google Summer of Code?
Achievements during OSGeo’s Season of Docs
We’re quite proud of our achievements during OSGeo’s participation in Google Season of Docs. Our allocated tech writers have amplified the effectiveness of our existing documentation communities, and our documentation communities have amplified the effectiveness of these tech writers.
- Felicity Brand worked with around 50 of OSGeo’s open source projects to update their Quickstarts as part of our OSGeoLive distribution of software.
- Swapnil Ogale worked directly with GeoNetwork’s documentation team, auditing the breadth of docs, and their quality, setting up templates for future docs to work to, and updating a number of the docs.
Further:
- We kicked off TheGoodDocsProject - “Best practice templates and writing instructions for documenting open source software.”
- In conjunction with OGC and ISO spatial standards communities, We kicked off an OSGeo Lexicon project, to coordinate official definitions for terminology used within the Open Source Geospatial (OSGeo) context. This will apply best practice definitions to prior haphazard glossaries.
- We did a deep-dive analysis of the documentation challenges faced by QGIS, one of OSGeo’s most successful projects. Surprisingly, their biggest problem isn’t a lack of tech writers or complicated tools (although they are factors). Key problems centre around:
- Poorly capturing community good-will and offers of assistance;
- A lack of direction;
- Struggling to keep up with a rapidly evolving software baseline;
- Insufficient writing expertise;
- A high technical barrier to entry;
- Documentation and training being generated outside of the core project;
- Awkward documentation tools and processes.
Thanks Google
Thank you Google for sponsoring Season of Docs. Felicity and Swapnil who you sponsored for us were great. We’ve learned plenty from them, and we hope you can take what we have collectively learned to help make future Season of Docs initiatives even better.
Postnote
This story was picked up by:
