-
Notifications
You must be signed in to change notification settings - Fork 171
Season of Docs Ideas 2021
Here we collate potential GoodDocsProject tasks for a senior technical writer to tackle under the banner of the Google's Season of Docs program.
We aim to create “best practice templates and writing instructions for documenting open source software”.
Our project is a spin-off from a 2019 Season of Docs project. We were looking for best practice writing templates and were surprised to not find an authoritative source.
We have put out a first alpha version of templates, a starting point and straw man, which we know can be improved.
We hope to create a "keystone project", similar in concept to a "keystone species" in zoology. A keystone species has a disproportionate influence on the ecosystem around it. Bees are a keystone species. Without bees, flowers don’t get pollinated, plants don’t reproduce, and animals stave. Git is a keystone project. Many projects would suffer if they didn't have access to git for software version control. TheGoodDocsProject aims to become a keystone project, helping the open source ecosystem flourish by empowering projects to create great documentation.
- We seek to create reusable elements and systems that organizations the world over can use to spin up their documentation efforts, regardless of their prior experience.
- We want more than best practices; we need to justify why - linking back to thought leaders and research.
- The tasks will involve a lot of research, reaching out to communities, discussions, and then collating finding back into templates.
- We wish to prioritise quality over quantity.
The best docs typically have been influenced by multiple stakeholders. This can be partly achieved using templates to collaborate between domains, timeframes, job roles, projects and organisations.
Writing templates for key doc types is our initial focus. This should start with identifying common elements for all templates - consider it a template for templates.
What information and guidance should be captured in each template? What supporting information should be provided in a supporting document? Each template should identify a target audience. It should be backed up by reasoning and research, which will help an author trust the templates are based on best practices, and know if and when it would be appropriate to deviate from the template.
There are multiple templates needed for different doc types. We will need to define target audiences, create the document structure, expected headings, along with writer guidance. This should be backed by evidence justifying why the template is best practice.
There is a lot of work to cover here. A Season of Docs project would likely only cover a subset of templates required.
Community developed documentation regularly becomes unstructured and difficult to navigate. This task involves researching, collating and distilling best practice information architecture patterns. It should:
- Help projects structure and then maintain their information,
- Help projects move existing docs to better architectures.
Within Season of Docs 2019, we found we needed to start by assessing the status of our current doc baseline. It helps if you can assess quality, currency, completeness and fitness for purpose of a project's documentation set. You can then apply a gap analysis between what you have and what you want to achieve, and direct resources accordingly.
This task is about building a doc audit checklist (or set of checklists). It involves identifying, classifying and cataloguing doc quality criteria. It will involve addressing from multiple perspectives, such as:
- The target audience(s).
- Each doc type's purpose.
- The maturity of the project.
- The short and long term capacity to write documentation.
Do you have more ideas? Talk to us about them.
For the sponsored Season of Docs 2021 writer position, we're looking to select:
- Someone who has been working as a senior technical writer, with a cross section of technical writing experience.
- Someone who gets involved, (think do-ocracy).
- Someone humble, who is quick to share credit with the team around them.
- Someone curious, who collaborates with others to research and refine ideas.
If you just starting in your tech writing career, and are looking for a paid spot, then I suggest looking at one of the other Season of Docs projects rather than this one.
We want to build our depth of senior tech writer experience. Most of us contribute in our spare time. If the possibility of great docs excites you, and you think you can help, then please join us.
If you use our templates in other Season of Docs projects, then please share your experiences and suggested improvements.
We have space for junior and aspiring tech writing volunteers, but our capacity to mentor is limited by our access to senior writers.
Feel free to reach out to us via our email list, or directly on slack, introducing yourself and noting what you'd like to get involved in. You can reach our Season of Docs mentors at season-of-docs AT thegooddocsproject.groups.io.
Here we have collected some background reading and links to blogs, and brain dumps of ideas we have collated to date.
- The Good Docs Project webpage.
- Lessons from Season of Docs 2019.
- A first alpha version of templates. These are a starting point - a straw man, which we know can be improved.
- Our issue tracker.
- Proposed list of templates that could/should be created.
- Raw ideas and links to best practices we have found so far.