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 talking about Season Of Docs with developers and writers I found we lacked a common understanding of the role of a technical writer. 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.

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 hinted provided an Example Projects page which helped, but I think it would useful to provide greater clarity around the value technical writers can bring to a project, the skills they bring, and roles they 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 documentation. Future Season of Docs initiatives should consider extending the focus to related roles.

• Most projects were under-resourced for triaging their documentation issue tracker. 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 non-programmer project users, who would like to give back to their open source community through documentation, but who wouldn't identify as technical writers. The Season of Docs tasks we have focused on includes helping empower these users to contribute to documentation.
• 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.)
• 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.

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, and 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 easier if the deadline was a week earlier or later.