Season of Docs Lessons Learned 2019

Season of Docs home page. A collation of lessons that we have learned while participating in the 2019 Season of Docs.

Organisation Application Process

Define "Technical Writer"

When I was talking about Season Of Docs with developers and writers we often lacked a common understanding of a technical writer's role. Many focused on the simpler and most immediate problems faced. In it's broadest sense, almost anyone involved in a software project is a technical writer:

• The developer who comments their code.
• The user or support person answering getting started questions within a community forum.
• The marketer describing the product's features.

So I started using the term "Senior Technical Writer" to focus conversations on harder writing problems, such as strategy and information architecture.

While everyone wants good documentation, I found that few share a clear definition of what it looks like, and fewer agree on tasks required to achieve this. The Season of Docs provided a list of Example Projects which helped, but I think it would useful to define technical writer roles more clearly, describing:

• The value technical writers can bring to a project,
• The skills they bring,
• The roles they can fill,
• And what writers need from developers to collectively become more effective.

Expand technical writing roles

Some common themes emerged when talking with our OSGeo projects about needs for documentation. We focused on tasks requiring high order writing skills, which are harder to find within open source communities. However, there are plenty of other important roles which are also needed. Future Season of Docs initiatives could extend the breadth of roles supported.

• Triaging a documentation issue tracker was typically under-resourced. It is hard to find volunteers for non-glamourous, time-consuming roles like this. And while it isn't specifically a tech writing role, it is important for the success of a tech writing program.
• We found plenty of project users who wouldn't identify as technical writers, who would like to give back to their open source community through documentation. This year's OSGeo Season of Docs tasks has focused on empowering these users to contribute to documentation.
• Community building and community support is a valuable way to attract project contributions to a project, be that via documentation, code, or something else. This outreach role is a valuable role worth fostering.
• Much of our documentation is written by developers using poor language choice. English documentation is often written by non-native English speakers. Future initiatives could support junior writers reviewing documentation against a specific style guide.
• Many writers are not technical. They are unfamiliar with wiki formatting, git, and publishing pipelines. If we can simplify tools we will increase the pool of writers willing to contribute to our projects. (This might be a focus area for Google Summer of Code.)
• Similarly, the documentation management and publishing infrastructure need to be set up and maintained. It is more within a programmer's skill-set than a technical writer's.

SeasonOfDocs blog aggregator

As many of us involved in Season Of Docs are writers, many of us will be blogging about it.

• I see Sarah has: https://ffeathers.wordpress.com/2019/05/02/season-of-docs-is-now-ready-for-tech-writer-exploration/
• Me too: http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html

I suggest it would be handy to set up a Planet Season Of Docs blog aggregator of people involved. Something like what we have set up at the Open Source Geospatial Foundation for those of us who blog about geospatial topics. https://planet.osgeo.org/

Deadline straight after public holiday

The organisational application was due on Tuesday 23 April 2019, the day after the Easter holiday break in many countries. Despite asking for input from our communities early in the application cycle, human nature tends to leave much till the last moment. There was quite a bit of last minute feedback received after people returned from Easter, which was too late to be included in our proposal. While this was a minor issue, I'd suggest that it would have been easier if the deadline was a week earlier or later.

Writer Exploration period

Concise Summary of Project Writing Tasks

Season Of Docs provides a list of Participating Organisations, with a summary of the project, links to the pages about tasks, and contact points. This is good, but I'd suggest slight refinements.

• Descriptions of projects cover the project's technology, however, the tech writer is likely more interested in types of writing required and how it matches the writer's skill set.
• I suggest keeping the list of projects concise (and probably encourage the technical description to be more concise, limited to 2 or 3 sentences).
• I suggest each project summarise their requirements from a technical writer.

Volunteers welcomed

Season of Docs only has space for a few paid writers, but this is an opportunity for projects to attract volunteer tech writers to join. Feedback from one senior tech writer I talked to:

"I'm interested in Season of Docs, but I'm not in a position to commit to a fixed deliverable due to my work/life commitments, and I haven't seen anywhere I can engage as a volunteer."

We should revisit Season Of Docs messaging to make it clear that volunteers are welcomed. And projects can be encouraged to apply strategies which help volunteers engage (such as providing "Howto get started" guides or similar). Here is how we approached with within our OSGeo Season of Docs ideas page.

Doc license

I see that a SeasonOfDocs specifies projects being written for need to be Open Source, but there doesn’t seem to be criteria that docs are written are to be under an Open License? I suggest this be corrected for the next Season of Docs.