[SeasonOfDocs] The problems faced by open source doc teams - and what to do about it

[Cameron Shorter]

I've written a detailed analysis about the significant challenges faced 
by the QGIS documentation team. (QGIS is an open source desktop 
geospatial application).

While research is specific to QGIS, I feel the lessons are broadly 
applicable to most successful open source projects. I'd be interested to 
hear feedback, and in particular, would be interested to hear whether 
the lessons should help frame next year's Google Season of Docs.

Tweet: https://twitter.com/cameronshorter/status/1203528611740831744

Blog post: 
https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html


    Summary

Many have tried to help QGIS docs, with limited success. I’ve collated 
insightful quotes from a bunch of their stories and then postulate 
solutions. Surprisingly, the biggest problem isn’t a lack of tech 
writers or complicated tools (although they are factors).

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.

This leads to an immediate case to:

  * Define and evangelise a vision and roadmap.
  * Prioritise funding and lobby sponsors to resource the vision.
  * Implement an information architecture review.
  * Sustain a community evangelist/coordinator to attract and nurture a
    broader doc community.
  * Sustain a trained technical writer to amplify the quality and
    effectiveness of the community.
  * Attract external docs back into the core.

Medium-term:

  * Ask the greater open-source community to address the usability of
    documentation tools and reduce the technical barrier to entry. Adopt
    improvements as they are developed.
  * Align with best the practices evolving withinTheGoodDocsProject
    <https://thegooddocsproject.dev/>.

While acknowledging the great work done to date, I feel the QGIS docs 
team has insufficient capacity and availability to skills to drive this 
agenda. Targeted and sustained investment should be applied to bring the 
quality of QGIS docs up to the quality of the software.

More: ... 
https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20191208/734aafa8/attachment.html>