Building The Good Docs Project template roadmap

Alyssa Rock — Tech writer. OSS community manager. DocOps enthusiast.
Jul 23, 2023, updated Sep 11, 2023 6 min read

After a huge team effort and a year’s worth of work, The Good Docs Project product management team completed the final stage of our first template product roadmap. In case you’re unaware, our project is working on creating templates for typical content types and documents used in open source software and beyond.

This template roadmap outlines the goals, vision, and work we want to accomplish in our upcoming release cycles for the project. In this blog post, I’ll explain how we brought our product roadmap to life.

A quick sidebar: I know it’s a little strange to apply the term product to an open source project where everything we produce is free. We had a few discussions about whether people would be allergic to using this term or not. Ultimately, we decided that it made sense in terms of describing the produce of our efforts.

The research phase

We wanted to ensure our product roadmap was informed by real data from real users. In order to collect this high quality data, we identified three research goals:

  • Discover which content types we should consider adding to our template roadmap.
  • Look for patterns in similar content types so that we could learn how organize the templates into template packs, which group templates together for a common purpose.
  • Identify which words, labels, and concepts people used for different content types to ensure we use accurate template names.

Template research goals

We then participated in three different Writing Days at Write the Docs conferences over the course of the year and invited Writing Day volunteers to help us with a template brainstorming workshop. We had 33 participants from a wide variety of geolocations and fields.

In each research session participants filled in sticky notes on a fun, and engaging Miro board to brainstorm content types for three different scenarios. Participants filled in 637 stickies over these three workshops.

About the workshops

The workshops consisted of three brainstorming exercises:

  1. Which types of content do you write regularly? Participants told us the most common types of content they write on a regular basis in their day-to-day work.
  2. Which types of content would someone need if they were building documentation from scratch? Participants told us which content types they considered to be foundational.
  3. Which types of content would someone need as their documentation project matures? They then reflected on what types of content someone would need as their documentation project begins to grow in complexity.

Brainstorming exercises

The analysis phase

At the end of the year, Joanne Fung, a volunteer from our community, painstaking entered in all 637 stickies in a spreadsheet so that we could analyze the data. (Thank you, Joanne!)

We then normalized the data by standardizing the content type names so that we could identify which responses were similar and which were unique. I need to give credit to the book Card Sorting: Designing Usable Categories by Donna Spencer for our normalization methodology. Her book came with a free Excel spreadsheet that taught me how to normalize data.

After that, we identified patterns and trends in the data to identify which content types were the most requested. We then analyzed the data to pull out key insights and make a set of recommendations for the template project going forward.

Data processing

You can view the original data at: Template brainstorming data. You can also read our recommendations in our Template brainstorming workshop report.

The decision phase

Next it came time for the project leads to sit down and decide which recommendations to take and add to our template roadmap. This involved about five 1-hour sessions with template working group leads who debated and deliberated about the suggestions until we created a rough draft of our Template roadmap. I need to give a huge shout-out to Cameron Shorter who joined me for all of these sessions and who provided valuable insights along the way.

We shared our draft with the community for comment and review. After the comment period lapsed, we incorporated their suggestions and locked in the final roadmap.

The key highlights on the roadmap were:

  • Formally adopting the idea of organizing our templates into template packs by a common purpose, use case, or popular documentation frameworks.
  • Determining which templates should go into our core documentation pack.
  • Deciding which templates should go into our OSS community docs pack.
  • Add new template packs to the roadmap:
    • API documentation
    • Diataxis
    • Docs for Developers
    • Documentation maturity
    • User research and audience
    • Internal documentation
    • Customer support
    • Communication strategy
  • We changed our final template deliverables to now require these files:
    • Template file
    • Template guide
    • Template process
    • Template resources
  • We added a new type of deliverable called The Good Docs Project Method articles for content that workshop participants requested, but which didn’t make sense as templates: information architecture, docs landing page, effective visuals, documentation analytics, documentation feedback, and more.

The socialization and work coordination phase

In the final phase, we worked on socializing the template changes and the roadmap with our template working group members. I held several meetings with all of the working groups to explain the changes and discuss any questions or concerns.

Then, we incorporated the changes into our project documentation by updating our contributing guide and our template deliverables document. We also built new issue templates for the four types of work the roadmap generated:

  • Missing template deliverable files
  • New method article
  • New template pack
  • New template

After defining our priority levels and labels, we then built out all our template backlog to support the work we needed to do to bring the template roadmap to reality. We also created a Templates kanban board to give us an overview of which templates are actively being worked on and which phase they are in.

I also need to give a shout-out to Michael Park who created a very sophisticated Google Doc file generation system for all the templates. We learned through A/B testing that our community members had a better experience and received better feedback when they authored in Google Docs instead of Markdown. So, Michael created a spreadsheet that could generate the template files that included our base template files.

Conclusion and acknowledgements

As I mentioned at the top, this represents a year’s worth of work by many members of the Good Docs Project community. I want to give thanks to:

  • Everyone who helped us run template brainstorming sessions across three Write the Docs conferences where we gathered the data that we used to build our roadmap. Thanks so much to: Deanna Thompson, Carrie Crowe Wattula, Cameron Shorter, Gayathri Krishnaswamy, and Felicity Brand.
  • To Joanne Fung for spending her holidays working with me to put the data in a spreadsheet and turn it into our template report.
  • To Cameron Shorter for spending many hours across several sessions talking with me through the report and finalizing our roadmap.
  • To the template working group leads and community members who reviewed the draft and made very helpful comments: Deanna Thompson, Joanne Fung, Gayathri Krishnaswamy, Lana Novikova, Tina Lüdtke.
  • To Michael Park for making his amazing Google Docs spreadsheet generator that we used to create all the Google Docs for these new issues. And to Ane Troger for doing a style review of Michael’s generator to make sure it conformed with our style guide.
  • To Tina Lüdtke for collaborating with me on the template packs and the issue creation process all along the way.

We have an awesome community!