Template brainstorming workshop report
Insights for our Template product vision
Data gathered from the 2022 Write the Docs Writing Day workshops
About the workshops
01
Why and how we ran the workshops
Goals for the workshops
Template packs
Look for patterns in similar content types to decide how to organize the templates into packs by a common purpose
Template roadmap
Discover which content types we should consider as we decide which templates to create
Naming conventions
Better understand which words, labels, and concepts people used for different content types to ensure we use accurate template names
About the workshops
Three brainstorming exercises
1
2
3
Types of content you write regularly
Participants told us the most common types of content they write on a regular basis in their day-to-day work
Basic documentation needs
Mature documentation needs
They brainstormed which types of content someone would need if they were starting a documentation project from scratch
They then reflected on what types of content someone would need as their documentation project begins to grow in complexity
Data processing
02
How we crunched the data to get insights
Data processing
Identify trends
We mapped out which content types were most common and looked for patterns in the data about when or why certain content types were most used
Input data
We put each participant’s responses for all three exercises into a spreadsheet, then compiled them into one list
Normalize
We standardized the names of the content types so that we could identify which responses were similar vs. unique
01
02
03
Recommend
We then analyzed the data to pull out key insights and make a set of recommendations for the template project going forward
04
Feel free to look at the data too
As you read the following slides, you’re welcome to look at the supporting data. You can access the spreadsheet at:
https://tinyurl.com/template-brainstorming-data
The spreadsheet contains many individual sheets. Some of the specific sheets used to create the insights for this slide deck are:
ContentTypesAction
Shows which content types were most mentioned and the recommended action we should take for each content type
Ex2BasicDocNeeds
TemplateNames
Shows the results of our second brainstorming exercise where participants told us which content types are needed for a starter doc project
Shows the standardized categories for the various content types and which raw responses were considered part of that category
03
Templates needed
Which templates should we create next?
Many of the most frequently mentioned content types already have templates:
But many additional content types that were frequently mentioned could be considered for future templates:
Some work has been done on glossaries in the project in the past, but we need to have discussion about how to reframe glossaries from the perspective of the template project
FAQs have some usability and accessibility problems and we’ll have to ensure the template effectively addresses those issues
Some content types weren’t as frequently mentioned but are still worth considering for future template projects:
Template packs
04
Which templates could be grouped together by a common purpose?
What are template packs?
Currently, our templates are offered in our repository in a flat organization style. Basically, all the templates are listed alphabetically. In the future, we want to offer template packs, which will organize the templates into packs by a common purpose. Note that a given template could belong to more than one template pack.
For example, for the template 1.0 release, we might provide these template packs:
Documentation starter pack
OSS community docs starter pack
API documentation pack
Divio documentation pack
Templates for content types most doc projects need
Templates for building a healthy OSS community
Templates for API documentation projects
Content types used in Daniele Procida’s Divio framework
Example templates
Example templates
Example templates
Example templates
Which templates should go into a basic documentation starter pack?
In brainstorming exercise 2, the template workshop participants told us which content types they felt were important for documentation projects that were just starting out. The most mentioned content types were:
Which templates should go into the OSS community docs starter pack?
Most of the technical writers didn’t seem to work on open source projects, and so most responses weren’t relevant to OSS communities specifically. However, Barrie and Fabio (participants at Portland) seemed to work in OSS based on their responses.
Their responses for Exercise 3 (what docs do you need as you grow) reinforced that we’re going in the right direction with the templates for the OSS community starter pack. For that pack, we’re currently creating templates for the documents that GitHub considers to be crucial for a healthy OSS community.
Which templates should go into the API documentation pack?
The responses also reinforced the need for a template pack that is specifically focused on API documentation. Participants mentioned the need for templates that we already have, but also suggested a few new templates that we might consider creating versions specific to APIs.
Existing templates
New templates
It’s worth noting that there were also clusters of similar content types that could be considered for future template pack development:
Internal documentation pack
Customer support pack
Communication strategy pack
Templates for internal company and doc team needs
Templates for providing better customer support
Templates for communicating with users and communities
Example templates
Example templates
Example templates
Template names
05
Do our templates use the most common names for that content type?
Should we consider renaming any existing or in progress templates?
Other observations about template naming conventions
Additional insights
06
What other observations came out of the data?
Specialized versions of templates
One thing we might consider is creating specialized versions of some of our templates to show how you might adapt that template for a specific, more specialized context. Some of the participants mentioned needing some more specific versions of possible templates, such as:
Content beyond templates
Many of the most commonly mentioned content types wouldn’t make much sense as a template, but would instead work better as either a written guide or as curriculum, similar to Lana’s Information Architecture guide that she did for our project in 2020. For example:
In particular, the responses to exercise 3 (which content types do you need as your documentation project matures) had these kind of content suggestions.
We should consider adapting our template creation workflow to also create guides or curriculum. The main difference would be where the content is published.
Validation for other working groups
Chronologue
Content strategy
Tech team
Blog and video
Nearly 5 participants mentioned that being able to look at good example documentation was key to creating effective docs
At least 6 participants cited the need for guidance around content strategy, including how to create a content plan and get stakeholder alignment
An extremely high number of participants cited the need for guidance about many aspects of doc tooling, including:
A very high number of participants work regularly on producing blogs for their company and could use more guidance.
Next steps
07
Next steps
Discuss
We’ll invite discussion about these results and engage the community in a discussion about the template roadmap. We can discuss it on Slack at #project-roadmap and possibly send out surveys.
01
Decide
We’ll come up with a plan to finalize the template product roadmap. Ideally, we’ll invite participation from as many templateers as possible before finalizing the plan.
02
Build issues
After the roadmap is finalized, build out the issues in GitLab to capture the work that needs to be done.
03
Get to work
Coordinate with the working group leads and templateers to get the work done and try to get our 1.0 release complete, hopefully this year.
04
Thanks to all who helped
make this report possible!
Deanna T.
Helped design the workshop and helped run the Portland workshop
Joanne F.
Helped create the data analysis spreadsheet and lots of data entry
Felicity B.
Helped run the Australia workshop
Cameron S.
Helped run the Australia workshop
Carrie C.
Helped run the Prague workshop and took notes at Portland
Gayathri K.
Helped run the Australia workshop