Nov 25, 2020
Good Docs, Anyone?
Here’s where to find them!
Everybody wants a good document — but who’s going to write it?
All of us have experienced the pain of missing, incomplete, or disorganized documentation at some point. We have often requested for that document to be ready somehow by the end of yesterday. And we have had to create that urgent document on the fly so many times, giving a novel meaning to a Sisyphean task of modern-day.
Interestingly enough, such hastily done documents have actually managed to save the day, the business purpose and sanity of all stakeholders involved, more often than not. Yet, we fail miserably at establishing and standardizing this simple process in our routine work.
Good documentation demonstrates clarity, simplicity, integrity, and currency. Such can only be achieved by adequately standardizing the process of documenting itself and by adhering to consistent guidelines throughout. In practice, however, most open source projects do not have enough expertise, time, and resources to dedicate to developing good patterns for high quality documentation output.
And so we tend to repeat alongside Sisyphus…. until the Good Docs Project comes to the rescue, that is.
The Good Docs Project — who we are and what we do…
The Good Docs Project has it all sorted. Well, not all of it sorted and certainly not right away. But we have started somewhere, and we’re getting there.
Tech writers, being tech writers, start off by clearly labeling, categorizing, and writing things down. We abhor chaos, clutter, and mess. We strive to maintain order, clarity, and consistency. By doing so, we hopefully salvage some self-sanity in the process. We have our documentation organized and like to poke our noses into the ones that are not.
We are a bunch of tech writers (with varied fields and levels of expertise) sharing the same pain points and striving at a common goal of producing qualitative and easily accessible documentation for open source projects.
Our mission is simple, yet complex at the same time:
“Best practice templates and writing instructions for documenting open-source software.”
— The Good Docs Project
That sounds too good to be true, I know. Given our mission, you might be surprised to see the extent of the community already involved in our on-going projects.
Contributions by the community, for the community, and driving the community!
Keeping with our vision of arriving at good documentation, we have identified some key areas where we can effectively help open source projects improve their documentation quality.
We have outlined best practice processes and created templates and guides covering the numerous aspects of writing good documentation. These processes and templates clearly describe our reasoning (referencing research where available) to help other writers decide when they should deviate from suggestions.
Quoting off our website, we believe that;
“Every project deserves a minimum level of Good Docs, but it can be really hard to know where to start or what to write.”
It is here that our ready-to-use resources will help you make a head start and accompany you throughout your documentation journey.
We help you define that minimum level of good documentation and strive to maintain expected standards and quality. We thrive in the knowledge that we are part of making the world a little better, at least in terms of documentation.
And so, a lot has been cooking and brewing in our pot of magic potions over the last couple of months since the start of Google Season of Docs 2020.
What’s in Store? — Our Solutions for the Season!
Here are some initiatives that we have either completed or are progressing towards completing:
- Templates — best practice templates for frequently used documentation types, including a Base Template for creating your own templates.
To access our templates (alpha phase), head over to our Github project and look at the progress we’ve been achieving. - Information Architecture Guide — that helps you arrive at the type of documentation you need to produce.
- General guidelines on how to start with documenting an open-source project.
- Style guides — Standards for writing, formatting and design of documents.
End of the day, it’s what you take home…
Technical writing is a thankless job. You could be held responsible for getting the procedural flow wrong such that this is one sure job where ‘no news is good news’ holds so true! All frustrations of a failed system, a malfunctioning product can easily be directed to the manual or the Standard Operating Procedure (SOP¹) that omitted a single step to saving the Universe.
Yet the rewards you reap go beyond (most definitely) the paycheck and/or the superfluous words of praise. With each little feat that didn’t go right today, your document tomorrow is made better by one less flaw. Slowly but surely, your document rates one point higher in terms of clarity and quality with each improvement you make.
Over at the Good Docs Project, we are committed to the progress of this journey in its entirety. We love contributing to and learning much from the community in the true spirit of volunteerism in making better documentation for tomorrow.
We are here to make the change that we wish to see in our documentation (tweaking Mahatma Gandhi’s quote a little there!)
Should you care to join in on the fun while doing a thing or two about getting your documentation right, feel free to reach out via our Slack channel and community forums.
You get to be a part of the silent revolution and leave your mark in docs, or in print, if you may.
Of course, good company and good documents are on the house but bring along your own coffee, and we shall help you ace your docs!
— — — — — — — — — — — — — — — — — — — — — — — — —
Acknowledgment and References:
- Although the Good Docs ambassadors are globally distributed, the Asia Pacific (APAC) team that I usually join in on for the video calls never fails to bring about good vibes and good laughs, restoring faith once again in all things good. My heartfelt gratitude to Cameron Shorter for inviting me over and absorbing me into the team, Jared Morgan for showing us all the glamour of tech writing (in true podcast style), Lana Brindley for her amazing zest about tech writing and the unwavering support throughout, Ankita Tripathi for all that cheerfulness despite the workload handled and Daniel Beck for the tech help always!
- More insight into our project is captured in Ankita Tripathi’s article Documentation templates and The Good Docs Project at:
https://idratherbewriting.com/blog/documentation-templates-good-docs-project/ - The Good Docs Project proposals for Google Season of Docs 2020:
https://github.com/thegooddocsproject/templates/wiki/Season-of-Docs-Ideas-2020 - License information for the use of The Good Docs Project resources:
https://thegooddocsproject.dev/licences.html - ¹SOP — Standard Operating Procedure — I do truly sympathize if you’ve ever had to create one of these from scratch! But the good news is that Good Docs has a magical Base Template that will help you create this type of documentation (and anything else you need) the proper way!
