Search results

Documentation templates and The Good Docs Project -- guest post by Ankita Tripathi

by Ankita Tripathi on Nov 17, 2020
categories: writing

Documentation templates not only help teams align with consistent approaches in docs, templates help guide engineers, non-writers, or other roles in creating content, removing the intimidation of a blank page. A group of writers passionate about templates have been working together to create templates for a variety of documentation scenarios. This group's project is called The Good Docs Project. The project makes available templates for API overviews, quickstart guides, reference, how-to topics, discussions, tutorials, and more. The following is a guest post by Ankita Tripathi, a member of The Good Docs project, discussing the project and her motivations for getting involved.

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.

Lack of proper documentation top reason for not joining open-source projects
"Lack of proper documentation" was the top reason developers gave for deciding against using an open-source project.

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.