State of the Good Docs Project, May 2022
This has been an exciting past several months for The Good Docs Project! Our band of passionate documentarians and developers have worked hard on our efforts to investigate, synthesize, and share best practices in technical writing. And we’re hyped to share our “state of the project” with the greater documentation community.
Love for our community
Before we dive into accomplishments and aspirations, we want to take a moment to thank our amazing community of contributors. Without all of you, this blog post would be pretty sparse! Us in project leadership are really proud of the supportive, diverse, passionate, and fun-loving community continues to grow.
We split our efforts up into a number of working groups, which allows our community members to focus their awesomeness on what they’re passionate about while letting them see and comment on what others are doing. We think of these groups as the many arms of the Doctopus!
The “production” working groups focus on making tools and material for others to use; namely for developers, but also for writers who are new to the craft or seasoned writers interested in how others in the broader technical writing community address similar situations.
We started this project to help out open-source developers with their documentation efforts, namely by providing templates both easy to adopt and robust in use. That’s a tall order! This working group concentrates efforts on a few core templates at a time, continually writing and peer-reviewing to provide something we’re confident that hits both of those marks.
We’re proud to release v0.2 of our templates, and we’re on track to keep adding and iterating on our templates in 2022 and beyond. If you’re interested in contributing to our templates, say hello on our Slack’s #templates channel. We have a few sub-groups, and are happy to connect you to a group that works for you!
One of our “templateers” is presenting at Write the Docs Portland 2022! Check out Chris Ganta’s talk, where he shares our group’s experience in peer writing.
Docs advocacy & education
Another arm of our project focuses on sharing advice, experiences, nuance, and more-through our new blog! We created this group last year, as a way to provide useful information that doesn’t quite fit in templates, but would still help our users produce stronger documentation.
We launched the blog earlier this month! So far we’ve covered:
- Marketing yourself - Why you need a tech writing portfolio, by Felicity Brand
- 3 tricks to overcome writer’s block, by Ryan Macklin
- And this post you’re reading now
Our aim is one article every two weeks, but our priorities are in quality posts with utility, not just posting for the sake of a constant rhythm. If you’re interested in contributing to this working group, check out the #blog channel.
We have a really fun group of people who produce a living example of our templates, for a fictitious project called the Chronologue! It puts our templates and practices to use documenting an application to view remarkable moments in time from the past and the future.
Our Chronologue group provides critical feedback for the templates, serving as a quality assurance group. We believe everyone can contribute to Chronologue, and currently have team members with coding, tech writing, and UX expertise on board to craft high-quality examples of what good documentation looks like.
Does this sound interesting to you? Come by the #chronologue-docs channel!
One of our newer working groups spun off to focus on helping people address the age-old question in documentation: “How do you convince leadership to invest in docs?” We’re in the brainstorming and bulleting out phase of the project, and have also collated a docs fact pack of great quotes.
If you want to help create great pitches for leadership, come introduce yourself in the #business-case channel.
Making documentation easier for open source developers isn’t just about writing the material, we also consider how to build and deploy documentation using our templates. But with the numerous platforms in the world, and how that number just gets bigger over time, the Doc Tools group recently shifted its goal to: Provide a set of high-level functional requirements for documentation systems, and starter templates, that are compatible with the overall vision of The Good Docs Project.
At the moment, this group is fairly thin, due to people involved also being involved in other critical parts of the project. This group’s ambition over the next couple release cycles is to get a strong foundation going. If that sounds of interest to you, we’d love to have you over at the #doctools channel! Especially if you have a strong interest in a specific content platform, because down the road we want to have examples of this in action for different platforms.
Glossaries are easy to set up for a simple use case, but hard to scale across teams and organizations. Within the Glossaries working group we are tackling how to establish sharable glossaries, which inherit terms from more authoritative glossaries. We are working on standards, scripting tools and processes to make it super-easy for any documentarian to add glossaries and popup term definitions to websites.
Are you passionate about what words mean, reach out to Cameron in the #glossaries channel.
It takes a lot of work to keep our broader efforts going, especially with as large and geographically diverse of a community as we have! These working groups do the less glamorous task of keeping the metaphorical lights on and guiding everyone to move in the same direction.
Community docs is one of our template sub-groups focused on what an open-source community needs to communicate goals and updates. They’re working on templates for READMEs, contributing guides, and changelogs. But they do something more than that, which is why they’re under this header: they also handle a lot of key internal needs that keep the project running.
Notably, this group also handles the critical role of onboarding new members around the globe. For instance, we routinely hold git training sessions for new members who are passionate about documentation but don’t have much or any experience with git and open source in general.
If you’re interested in how to keep the heart of a community beating, come talk with them at #community-docs.
If it sounds like our overall project doesn’t have focus, you’d be right! At least, you would have been a year ago. Content strategy came about because we recognized a need to have focus with our project, lest all of our efforts and passions spread us too thin and in conflicting directions.
Last year, we recognized that we needed to build a comprehensive strategy for all of our content: the overall website, the advocate and education material, the templates, social media, etc. But rather than the group “reining in” our members’ passions, it’s working to provide the structure needed to help our members accomplish goals and deliverables.
This blog post and the tweet pointing to it are two examples of this group’s successes, not directly, but through empowerment. Thank you, CS! Check out #content-strategy to find out what they’re up to next.
Speaking of focus, we’ve mentioned “release cycles” in this article, but what does that mean for our project? Well, that’s what this group is tasked to handle! Last year, we decided that we want to peg significant releases timed around Write the Docs conferences. They are useful deadlines since as many of us are actively engaged in that community.
The release management group’s first big public-facing achievement is this season’s release! But they’ve had a lot of smaller milestones achieved over the last several months, which paved the way for our project to have a coherent release strategy. You can engage with that group in our #general channel.
We’d love to welcome you!
We have more groups than these, though these make up the bulk of our active initiatives and members. Some groups are aspirations from members who don’t have the bandwidth to pursue them at the moment. Others are activated as needed (such as our code of conduct group).
And of course, if this post makes you think “hey, maybe I could contribute,” OMG we love you. We invite you to fill out our welcome survey. Or say hello in #welcome, and feel free to message any of the co-chairs: Alyssa Rock (@Alyssa Rock), Carrie Crowe (@Carrie Crowe), or Ryan Macklin (@macklin).