-
Notifications
You must be signed in to change notification settings - Fork 171
Season of Docs 2021 Proposal
This is a proposal to have a senior technical writer sponsored under Google’s Season of Docs to amplify the effectiveness of other template authors, by mentoring and supporting them in writing templates for The Good Docs Project, and improving processes along the way.
The Good Docs Project is focused on providing best practice templates, writing instructions and guidance for documenting open source software. The first documentation templates were published in 2019. Since then we have been building and polishing the processes tools and doctype templates behind the project. In 2021 and beyond we wish to:
- Strengthen consistency between doctype templates by basing them all upon a common base-template.
- Lifting the quality of all templates, introducing what we have been learning to date.
- Increasing the breadth of templates covered.
Within The Good Docs project, our ability to grow our community is limited by our capacity to onboard new members and help them become productive. This results from a combination of:
- Limited process and associated documentation for onboarding.
- Limited capacity from experienced community members to mentor new members.
- Limited bandwidth to update our base-template and associated guides as we learn more.
For Season of Docs 2021, we wish to engage a senior technical writer to address these challenges. We are looking for a senior technical to amplify the effectiveness of the technical writers who are building templates within The Good Docs Project. This will involve a combination of:
- Improve project onboarding documentation and associated processes behind the docs.
- Polish, harmonize and extend existing templates, such as instructions within the base template.
- Some review of incoming pull requests to the templates repository.
- Some mentoring of template authors.
Primary Deliverable: Harmonized base templates and related docs
- There is overlap between our base-template, the doc audit checklist, and our information architecture guide. This task will involve comparing, harmonizing and consolidating the similar information shared between these documents.
Primary Deliverable: Incorporate lessons learned into our base-template or associated docs
- Improve our onboarding documentation.
- As our community improves our understanding of templates, ensure these lessons are incorporated into docs.
Secondary Deliverable: Review of incoming pull requests to the templates repository
- In order to understand the onboarding challenges, contribute to the reviewing of incoming pull requests for templates.
- Capped at two hours per week.
Secondary Deliverable: Mentoring of template authors
- In order to understand onboarding challenges, opportunitistly help a new author or two to get started. (This depends on new authors coming on board.)
- This should help with finding holes with the onboarding process.
- Capped at two hours per week.
Deliverable: Attend and contribute to meetings
- During the duration of the engagement, engage as part of the community in one hour weekly one hour meetings. This might include meetings in two time zones.
- Attend additional ad-hoc meetings as needed. Up to say one hour per week.
Deliverable: Project Case Study
- The tech writer will act as the primary author of a case study in the success and challenges faced during the Season of Docs project.
- This case study will be co-authored by the project mentors, and interested community mentors.
This project is developing and refining doctype templates and processes based on the knowledge we have in the community to date. We anticipate some of the newly generated content to be of experimental quality. It may contain placeholders and sections to be filled in later.
- Unlimited mentoring and reviewing of documentation from new writers. The tech writer and mentors will need to prioritize where to focus such effort.
- Development of doctype templates, beyond what has been described in the “In Scope” section.
Due to the exploratory nature of the project, and the unknown size of the volunteer community that will be supported, there is expected to be changes desired for the scope of the project. Deliverables may be adjusted, or old deliverables replaced by new ones, as negotiated by mutual agreement between the mentors and the technical writer.
Such changes should be documented in writing, such as in running meeting notes.
We are looking for a senior technical writer, with experience mentoring others, preferably within open source communities.
We will look for such a person both within our existing community and will also consider sourcing from the list and forums established by Season of Docs.
There is a difference between metrics we’d like to have compared to metrics which we can easily and sustainably measure within our community. Here we list what we think we can sustain, described using (Goal, Indicator, Metric).
Goal: Lift the quality of open source software documentation.
Sub-goal: High adoption rate of our quality doctype templates
Sub-goal: Improved onboarding of template writers and community contributors
- Indicator: Wide update of our templates
- Metric: Count projects which credit us as a source from their documentation.
- Success metric: Some projects linking back to our project from their docs.
- Indicator: Community size and health
- Metric: Count activity of active contributors in slack channels and email list.
- Metric: Count active contributors to the project repositories
- Success metric: 10% growth per annum
The following metrics are not tied directly to the Season of Docs scope, but are applicable to the wider success of The Good Docs Project:
Sub-goal: Develop quality doctype templates.
- Indicator: Number and quality of templates
- Metric: Count the number of our templates classified by us as (individual contribution, community reviewed, alpha, production)
- Success criteria: All doctype templates from 2020 baseline to be migrated to the base-template format by end of 2021
- Success criteria: All core Priority 1 templates matured to “community reviewed” state by end of 2021
| Item | Amount $US | Notes |
| Technical Writer 1 | 4,500 | |
| Supporting organization overheads | 300 | Incidentals such as bank processing fees and good will. If allowed, it would be good to use this for swag for volunteers in the community. |
| Swag | 200 | We have the potential to attract between 10 and 50 active contributors to this initiative, and it would be nice to provide each with a tee-shirt as a sign of appreciation. We’d prefer to defer organizational and mentor fees into this collective swag budget item and spread the love. |
| Total | 5,000 |
- The Good Docs Project, and some of our mentors have participated in both Google Season of Docs and Google Summer of Code.
- Many of our mentors and participating community members are professional technical writers.
We believe that this depth of experience provides us with insights and experience to build doctype templates and processes which will help the breadth of the open source ecosystem.