Source of Truth Documentation

Building from my prior post on known gaps to fill after changes to my WordPress Contribution hours, I wanted to take some time to lightly document my approach to creating the Source of Truth to benefit a small crew of folks who are planning to carry this work forward. See it as similar to prior public documentation I’ve done for more experimental or tangential things. For now, a big thank you to the folks who are planning to jump in! I have always wanted this to be a more communally driven effort to avoid the bus factor but haven’t been able to make it happen.

Biggest piece of advice: make it your own and improve it. Just because it was done one way previously, doesn’t make it right. I can be very regimented to a fault once I find an approach that works but that doesn’t make it the best approach, especially with a team of folks who can work on this vs an individual.

Template

Here’s a template you can use to get started for 6.8. I create this every single time for myself when I start a new one of these!

Process
At a high level, there are three stages to this work:

• Gathering information
• Creating and refining the content
• Spreading the word

Alongside all of this is coordination work around who is doing what, setting the timeline, etc.

Timeline
The timeline is somewhat flexible but the aim should be to get this information to folks as early as possible while still ensuring the reliability of that information. Right now, that’s resulting in an early release in line with Beta 1 and a more formalized, “nothing is changing” release around RC 2. Somewhere around Beta 3, the source of truth is then shared publicly. Usually this has been shared on nomad.blog but, as of the last release, Birgit has kindly let me use Gutenberg Times and I would prefer to see it there. It makes more sense, has a built in audience, etc.

Gathering information
This includes everything from reviewing roadmap posts for the release, reviewing all of the Gutenberg release posts since the last major release, testing the releases/features yourself, reading GitHub issues, talking to individuals working on various features to know the likelihood it’ll land in a release, and more. At this point, don’t worry too much about determining what will make the release—it’s best to aim for everything, including potential items, than to miss something. Be as detailed as possible as the details are what makes this document powerful.

Creating and refining the content
At this point, you should have loose outlines of top features and will need to flesh out the content itself. Don’t just focus on describing a feature, share how this will help someone with their WordPress site, their clients, etc. It’s important the impact is focused on just as much as an accurate description. When in doubt, bring in subject matter experts to help review. As part of this, have an opinionated take around the important features for the release. This is hardest to do! Doing it well and right though results in making the release squad’s life easier as they can then pull from it for the About page, microsite, release announcements, etc.

Of note, for the 6.7 source of truth, this was the first time I used AI to help. I mainly did it to rewrite my writing to be shorter or clearer. I didn’t use it to explain or summarize features as I didn’t trust it would capture the nuance. I would give AI a try here once more to see how it can help! It’s an area I haven’t quite cracked yet.

Spreading the word
This involves a few parts:

• Sharing in various relevant slack channels like the release channel.
• Sharing individually with specific community members, especially anyone doing education, documentation, etc.
• Posting publicly when the time comes.

For the latter, it’s important the right context is given to folks. I usually include a clause at the beginning like so when it’s in a google doc form (early release around beta 1!) before a public release (around beta 3).

Some things to note before diving in:
– Do not copy and paste what’s shared within since it is a communal document. If you do that, you are risking the embarrassment of someone else doing the same and it appearing as though you copied each other.
– You will have Comment access but not edit access. This is intentional – please comment if you have any questions/concerns/feedback and I’ll follow up. You’re welcome to obviously just ping me here too
– If there are drastic changes, this document will be updated and you will be alerted.
– Each item has been tagged using best guesses with different high level labels so that you can more readily see at a glance who is likely to be most impacted.
– Each item has a high level description, visuals (if relevant), adoption strategy (if relevant), and key resources if you want to learn more.
Enough with the context setting — enjoy. If it proves to be helpful, would love to know how. It really helps to get a sense of how folks are using the doc and what can be done in future iterations.

As folks share what they did with the doc, keep track of it in order to better understand impact.

Tips & Tricks
At a high level, here are a few tips and tricks:

• Make the structure your own. Nothing is set in stone.
• Get clarity on items that are uncertain ASAP and ensure you have a spot where you can check the status without needing to ping someone repeatedly.
• Reuse whatever you can from Gutenberg release posts design wise to provide assets and ask for help for anything leftover. This is going to be hard with limited design resources and you might just need to create your own (I regularly do that).
• Structure the doc itself in a way that shows the highlights of the release prominently.
• Run a retrospective at the end so you can gain insights for next time.
• Be careful about the release squad reusing the content for the Beta 1 announcement post and encourage them to be inspired by the Source of Truth but not to wholesale copy/paste. This burned me a few releases in a row and it’s no one’s fault. It’s just something to be clear upfront around and check for as it isn’t a great look to have that content copy/pasted.
• Jonathan Desrosiers is a great ally for Trac related items to include.
• In my experience, I encourage all of you to be very realistic and transparent about how much you can put towards this doc. Where it has been hardest is when I’ve tried to collaborate with others only to have them ghost on work I needed done. It helps us all to know what folks can contribute.

Workflow tip video

Here’s a video I recorded and shared talking through my recommendations for how to work on this as a group to ship it on time. Take it or leave it!