View source for Season of Docs Lessons Learned 2019

[[Season_Of_Docs_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 [https://developers.google.com/season-of-docs/docs/project-ideas 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 [https://developers.google.com/season-of-docs/docs/participants/ 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). [https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought Here] is how we approached with within our OSGeo Season of Docs ideas page.

== Communication Overload ==
=== FAQ ===
Alanna Irving provided a nice [https://medium.com/open-collective/our-season-of-docs-faq-d8d5fc89422b FAQ] for the Open Collective Season of Docs. This is a good idea, and is helpful for answering requests.

=== Project Description Overhead ===
With 50 projects providing long lists of writing tasks, there is a high overhead for applicants wanting to read each project, then target an application to each project they are interested in. How can we help applicants find projects which match their skillset more efficiently? And how can we help balance applicants between projects? 
# Maybe have a graph showing the number of applicants per project, and then applicants will move to projects where they have a better chance of being selected.
# Suggest we create a taxonomy of tasks which can be allocated to projects. Eg: Information Design - will accept 1 stipend person, up to 4 volunteers.

=== Applicant Overload ===
We received plenty of applications from hopeful participants. Some participants spammed all projects. The logistics of each project processing each of these requests is expensive to our community and we should work out strategies to reduce this. I'd suggest:
# Ask applicants to respect the time of projects.
# Provide a checklist of things to check before applying. (Do you qualify for minimum XXX before applying)
# Are you interested in volunteering, if so, then have a look at this separate list ...
# ...

== 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. (I was asked if it would be acceptable for someone to participate by extending proprietary training material about open source software. I'd suggest we should cover this scenario.)

= Development Phase =
== Problems Open Source doc teams face ==
I’ve written a detailed analysis about the significant challenges faced by a successful open source project (QGIS), and strategies to address these. (Surprisingly, it doesn’t start by adding technical writers). While specific to one project, I feel the lessons are broadly applicable to most successful open source projects.
 
* Tweet: https://twitter.com/cameronshorter/status/1203528611740831744
* Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

There are lessons in here which I think should be absorbed into Season of Docs:
* Docs should start with an information architecture
* Typically the most value a senior tech writer can provide is to amplify the effectiveness of other writers. Refer to [https://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring techies to become great writers].
* Community leadership is really important.  
* Docs are much easier if you can make use of best-practice templates. Refer to [https://thegooddocsproject.dev/ The Good Docs Project].
[[Category: Season of Docs]]

==Writing tools don't match writing workflows==
Why hasn't someone created a writing tool which is as easy to use as Google Docs, but which backs into a wiki format and git at the back end? This is a significant technical hurdle which hampers to capturing of incidental contributions from an Open Source Software community, and even slows down developers. This was picked up in our analysis of the QGIS docs community and also TheGoodDocsProject community.
===git - pros and cons of git===
===wiki markups - pros and cons===
===google docs - pros and cons===
===gitdocs===
gitdocs looks promising. Has anyone tried it and can report back?

==Missing Measurement tools==

==Missing templates==

==Gap Analysis==

==Missing quality definitions==

==Glossaries and lexicon management==

==Finding motivated contributors==
A goal of SeasonOfDocs is to "bring open-source and technical writer communities together, to the benefit of both. Together we raise awareness of open source, of docs, and of technical writing."
To realise this goal, let's consider the motivations of people involved. As explained in Eric S Raymond's first rule of open source in [http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s02.html The Cathedral and the Bazaar]:

''# Every good work of [open source] software starts by scratching a developer's personal itch.''

Software developers write great open-source software because they are both competent (as developers) and motivated (with an itch to scratch).

The challenge we face with open source docs is that it is hard to find people who are competent, have an itch to scratch, and are not faced with a significant barrier to entry (for the person's skill profile).

===Software users:===
Interest:
* Often are very appreciative of the free software that developers have given them and want to give back in some way.
* Have often been frustrated by poor documentation.
* After finding a solution, are often prepared to write up a specific doc problem.
* Might be prepared to write up a doc section if they feel it would be helpful and appreciated.

Hindered by:
* Technical ramp-up required to learn to write docs (such as git, wiki markup languages).
* Lack of writing experience, experience with style guides, document structures, etc.
* Lack of understanding of the documentation strategy and what sort of documentation should be written.
* Often don't feel worthy to provide contributions. "Developers know the software better than I.", "I'm not a trained writer."

===Software developers:===
Disinterest:
* Would prefer to write code.

Hindered by:
* Lack of writing experience, experience with style guides, document structures, etc.

Interest:
* Often acknowledge the importance of documentation and would like to see their product as being polished.
* Might be suffering from frustrated user community asking questions because they can't find good docs.

===Technical Writers===
Disinterest:
* Typically are not users of the open-source application, so haven't used the documentation and haven't experienced a driving itch to fix them.

Interest Google Season of Docs:
* Have joined Google Season of Docs, maybe wanting to learn about open source, maybe because they are getting paid, maybe because working on a sexy Google project is interesting or would look good on the resume.

Interest in TheGoodDocsProject:
* We have attracted multiple VOLUNTEER tech writers to help create writing templates as part of [https://thegooddocsproject.dev/ TheGoodDocsProject].
* In this case, tech writers are scratching an itch. The templates they've been motivated to create will help address challenges writers face on a daily basis.
* When shared with open source projects, the templates will remove barriers to entry for project users and developers, opening up the potential contributor base to open-source documentation.

==Barriers to entry==