Doc templates workshop

The Good Docs Project is about to run a series of one hour workshops to brainstorm:

• What constitutes a good doctype template?
• How should we capture and present best practices in our base template docs?
• Which templates should be worked on next?

When

We'll start around March 17, 2021. If you’d like to contribute, please vote for your preferred time slot and help us understand how many people will attend: Doodle poll.

Feedback will be used to update our base template, and set the direction for future template development.

Sessions

Pre-reading:

• To contribute meaningfully you should read our base template docs, and be ready with questions or suggestions.

Session 1: Overview

• Walk through of our current base doctype template
• Explain logic behind each section
• Field questions
• Identify topics to discuss in future sessions

Session 2,3: Topic discussions

• Deep dive into topics identified in session 1
• Absorb actions to update the base template
• Volunteers to test theories by starting to write a template

Why participate

Participate if:

• You are keen to help shape best practices in doctype templates.
• You’d like to adopt a basetype template.
• You have expertise, bandwidth and commitment.

Background

To date:

Within The Good Docs Project we are creating best practice templates and writing instructions for documenting open source software.

In our first release in 2019, we’ve created 0.1 core templates, based on insights from multiple senior tech writers. These are quite good, but in the interim we’ve been improving these templates, building up processes, and refining our thinking about what makes a good template.

This has accumulated into our current base template docs. As of March 2021, these docs are draft ready, but untested.

This phase (first half of 2021):

Next we are inviting tech writers to adopt and create a template from our prioritized wish-list of templates to write. We will be testing our base template by using it - and we will collect feedback into the base template.

Adopting a template is a reasonable commitment, but is achievable for one person to tackle. It involves:

• Learning the base template.
• Researching and documenting best practices in use for your doctype.
  • This typically involves researching business processes and communication theory.
• Collaboratively refine the template with others.

We’ll move through stages of:

• Nothing -> Something -> Better -> Best

At the end of this push, we expect to have a more consistent, core set of templates, along with a bunch of lessons to roll into future phases.

Future:

In future:

• We’ll refine our templates drawing upon the lessons we’ve learned.
• We’ll expand the range of templates we cover.