[Qgis-community-team] Tasks for writing Documentation

[Cameron Shorter]

I've drafted a post about what I think the GSoD should focus on. I plan 
to publish in on my blog after Google's announcement on 2 April.

https://docs.google.com/document/d/1QjPs_Erc9u4DWtAQTSVSHPyDHQNlXYNvsiMDDOM2sXo/edit#

Feel free to comment and add suggestions. (Please log in with your 
google profile before commenting so I can see who has said what).

--

**

*Google has initiated a Season of Docs 
<https://developers.google.com/season-of-docs/>aimed at improving open 
source documentation. It’s an opportune focal point to tackle big 
documentation challenges.*

*

Open source, like many technical projects, often has patchy 
documentation. It is in various stages of currency, completion, 
relevance, verbosity, and quality. How can we consolidate it to become 
consistent, concise, intuitive, accurate, minimises learning and ramp up 
time, and is sustainably maintained to match continually evolving 
software releases?


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

  *

    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 minimise
    maintenance and archive outdated material?


    What to focus on?

To maximise the impact of Google Season of Docs, I’d suggest promoting 
initiatives which:

  *

    Use and contribute to documentation best practices,

  *

    Use templates and guides for key documentation types to help
    cross-domain collaboration,

  *

    Apply cross-discipline mentoring and support,

  *

    Refine workflows and tools which reduces the barrier-to-entry,

  *

    Pilot all of the above and capture lessons learned.

This might involve:

  *

    Auditing existing documentation,

  *

    Defining a writing strategy,

  *

    Mentoring a project’s developers, users and trainers to write a
    specific documentation type,

  *

    Contributing back to best practices.


    Further Reading

General:

  *

    Inspiring techies to become great writers
    <http://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html>

Documentation Strategy:

  *

    What nobody tells you about documentation
    <https://www.divio.com/blog/documentation/>

  *

    Document type definitions
    <http://cameronshorter.blogspot.com/2018/06/technical-documentation-writing.html>that
    I’ve written before.

Research into building open source communities:

  *

    Analysis of over 170,000 open source projects to identify success
    factors
    <http://cameronshorter.blogspot.com/2018/11/comprehensive-research-into-open-source.html>

  *

    Success factors of episodic volunteering in Open Source
    <https://cameronshorter.blogspot.com/2018/12/catching-elusive-episodic-volunteer.html>

Geospatial Open Source

  *

    High Impact writing tasks for OSGeo and OSGeoLive
    <https://docs.google.com/document/d/1yriJoybYjsCKhprNLNGGanw8HRA5Z8GhrNrA5RjavUU>

*

-- 
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/qgis-community-team/attachments/20190401/90403f11/attachment-0001.html>