Documentation templates and The Good Docs Project -- guest post by Ankita Tripathi
- Getting involved in The Good Docs project
- The Good Docs Project
- Who does this cater to?
- What is the project achieving with this?
- What are the other Good Docs Projects?
- About Ankita Tripathi
Getting involved in The Good Docs project
I was surprised to learn that even after all these years of dealing with open-source projects, one exhausting factor persisted: “Handling of a shared vision.” When a team comes together to contribute to an open-source project, they forget its importance over time. And what suffers is proper maintenance, documentation, licensing, or chalking out guidelines. While all these factors need supervision, my focus for this blog post is on documentation.
But before I dive into the unorthodox styles and practical reasons behind the existence of The Good Docs Project, I want to lay out how it all began.
It was about three and a half years ago when I accidentally found my way to Technical Writing. As some of you might know, I was in for some trouble. Technical writing doesn’t happen to you by luck; you slide your way toward it.
When I received an offer from a startup and a well-known organization simultaneously, I had to make a difficult choice. The only reason I chose the startup over the well-established, prominent, and opulent organization was that THEY HAD NO PROPER DOCUMENTATION. In my defense, I knew that I would understand the pitfalls of documentation better if I started from scratch. But what I didn’t realize was that in an isolated place somewhere lies something called open-source documentation. Open-source documentation can often be overlooked or buried under all the software fluff, and I had no idea how to deal with it.
The problems for open source projects erupt when the entire code base is ready while missing:
- A polished README
- A comprehensive step by step guide
In fact,
- In 2017, GitHub surveyed 5,500 randomly sampled respondents sourced from over 3,800 open source repositories on GitHub.com and other platforms. One of their key findings was that incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents.
- 72% of surveyed developers say “Established policies and documentation” is a key decision factor when choosing open source.
- In DevRel 2019, Jo Cook inspired and empowered users and techies to become great writers and overcome the documentation barrier.
THAT’s a GIANT gap.
This data is probably why the startup I joined and many other large open-source organizations have suffered the wrath of having unpolished and inadequate documentation. The need for structured documentation that could save end-users’ time and a painful headache was of utmost importance.
I started trying to lay out rules and strategies for maintaining a perfect open-source documentation suite. The more I dug for guidelines, style guides, or templates, the more frustrated I became with no fixed answers.
The loopholes in documenting an open-source project are multi-faceted, varying for different user personas:
- Developers, who have impostor syndrome and believe they just can’t write docs
- Project leads, who don’t prioritize documentation over other tasks
- Writers, who have high barriers to entry when it comes to good documentation
Imagine having an upcoming investor event. You prepare everything but are not sure where to start with writing your pitch. If only you had a pitch template that could make it easier, giving you enough time to focus on other important tasks.
Did you see the solution here?
YES!
TEMPLATES!
The bazinga moment happened when a team of technical writers who have been registering all these problems came up with the idea of templates. That group eventually became The Good Docs Project: An initiative launched by many seasoned technical writers and open-source champions. They wrapped their hands around the problem and came up with a solution to define a template or a how-to guide for creating open-source documentation.
I stumbled upon the project when they called for members from the Season of Docs, Write the Docs, and other communities to form a global team.
The Good Docs Project
The Good Docs Project came into existence because the founders wanted to create a suite of templates and best practices for open source technical documentation. Templates that could be extended and reused by anyone according to their requirements.
We know the documentation scope expands when we look at the diversified arenas a software cycle goes through:
- A quick start guide
- API documentation
- Knowledge base
- Tutorials
- FAQs
- Style guide
- Community forums
We started by creating a suite of templates so that cross-domain open source projects can improve their documentation and increase contributions to their projects. But is it so easy to customize a template?
Who does this cater to?
Our concern with the creation of basic templates was to entice everyone to use them. Our target audience for Good Docs templates are:
- Techies who are writing docs (software developers and software users). These folks often have messy open-source documentation and want to bring it up to a polished level.
- Software developers who need to document their project. These folks often need a template, clear writing instructions, or an example they can easily adapt or follow.
- Documentarians who are reviewing documentation. These folks often need guides and checklists to validate that the docs they are reviewing are indeed “good docs.”
What is the project achieving with this?
With the launch of Season of Docs, the Good Docs team gained a couple of tech writers. They have been working on creating a base template and a user guide. Now that we are halfway into the project, our deliverables include the following:
- Excellent examples that follow best practices aligned with the developmental practice of looking at a real-world working example.
- Templates that make best practices easy to implement, which prevents blank page anxiety.
- Guidance about how to improve your docs. It’s hard to write task-based docs when you haven’t identified your audience or thought about what the tasks in the workflow are.
- Resources that support writers and other documentarians in their careers, such as guidelines on how to measure and communicate the value and impact of your documentation work. These include reporting templates and guidelines for using and interpreting analytics data, etc.
- Best practice templates and writing guides as per Daniele Procida. These include several types of content: tutorials (learning-oriented), how-to guides (problem-oriented), explanations (understanding-oriented), and technical references (information-oriented)
- General guidelines on how to start with documenting an open-source project.
- Style guides
What are the other Good Docs Projects?
While The Good Docs Project covers many aspects of open source technical documentation, the umbrella project remains the same: solve the most challenging writing problems with templates.
The Good Docs Project is also handling the creation of templates for glossaries and has collaborated with organizations like Open Source Consortium (OGC), Open Source Geospatial (OSGeo), and ISO TC211 to help them create a consistent set of terms & concepts.
In retrospect, I realize that, unknowingly, I am part of a revolution. Not all heroes wear capes, and not all revolutions start single-handedly. We are proud to acknowledge that our most significant strength has been the formation of a community. The community brought in their expertise, solutions, remarks, collaborations, and, above all, IDEAS. With every passing day, I am becoming a better writer, leader, and self-sustained individual who is still contributing to bringing in a change by being a part of this project.
If you feel you connect with this and possess a zest to contribute, join our Slack channel. Be a part of the transformation. Because open-source revolutions do not happen in a jiffy. It takes time and a whole amount of dedication to bring about change. So, join our revolution and be a part of the 40% who want to make a difference in the documentation world!
About Ankita Tripathi
Ankita Tripathi is a technical writer and community manager at Unbxd. She started working as a Java developer at Infosys, then as a content creator, and then transitioned to technical writing several years ago. She focuses on the glossary project in Good Docs. You can connect with her on LinkedIn or on Twitter at @ankitatr.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.