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.

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.