The The Good Docs Project is excited to announce our latest release of documentation templates! This version 1.3 is codenamed Friendship. The Friendship release is inspired by the twenty-seven bridges throughout the world named Friendship, including the pictured Thai-Lao Friendship bridge which connects Thailand and Laos.

Template standardization

One of the other big highlights in the Friendship template release involved the efforts by the Tech Team to standardize our template suite. Led by Bryan Klein, Michael Park, and Alyssa Rock, the Tech Team made several changes to the templates to improve downstream consumption. They standardized the template file naming conventions to ensure consistency, repaired broken links, and ran all the templates through a Markdown linter to ensure it was well-formed.

The team also created an index.json file that includes important template metadata. This new file includes:

A list of the contributors for the template so that we can give proper recognition to our community members.
A list of the template packs to which the template belongs so that they can be categorized on our website.
A mapping of the files associated with that template.

Lastly, we introduced improvements to our merge request review process to ensure we don’t experience any additional filename and Markdown quality drift. We hope these changes will make it easy to quickly use and consume our templates downstream.

Friendship templates

The Good Docs Project empowers people to create high-quality documentation by creating and sharing our templates. For the Friendship release, we are excited to share a newly enhanced release notes template and a brand new changelog template.

Let’s take a closer look at these templates!

Release notes template

The updated release notes template is authored by community member Leigh Hutchens. The release notes template is an excellent starting point for you to to create release notes for your project. Release notes communicate improvements, bug fixes, and known issues to users. Release notes are important to document and share because they act as a communication tool betweeen you and your users, keeping users up to date on the latest changes. Documenting and sharing high-quality release notes builds trust with your users by demonstrating that you actively maintain your product and care about the user experience.

Leigh documented and added the process and resource file to the release notes template. Additionally, she also made some improvements to the original template as well. She created and introduced her great idea of "mini-templates" as part of this project. "Mini-templates" are short, sentence-level examples for different ways to phrase different types of release note items. For users who struggle knowing to write individual release note items, these examples aim to help them overcome writer’s block and write clear, well-crafted release notes.

When asked about "mini-templates" and her template writing process, Leigh shared:

Working on the release notes templates for The Good Docs Project was both a fun and insightful experience. One of the coolest things that I got to do was introduce the concept of "mini-templates", which is designed to make the writing process more modular and adaptable for diverse needs. The use of mini-templates assists in streamlining the overall structure and organization of each template but also offers users a flexible starting point customized to the user’s specific release notes requirements. Along the way, I gained a deeper appreciation for how clarity and consistency in documentation can empower teams effectively to communicate changes to their users. This project underscored the importance of balancing structure with adaptability, ensuring that our templates remain both practical and versatile for the community.

— Leigh Hutchens

This template is Leigh’s first contribution to The Good Docs Project. In June, Leigh joined the project and became an active member of the Team Dolphin Templates working group. The release notes template also represents the first template contribution from the Team Dolphin Templates group and is a major milestone for that working group.

The release notes template is a part of the core documentation template pack. The core pack is The Good Docs Project’s flagship template pack, so we’re very excited to see such a big enhancement to this template. Congratulations and big thanks to Leigh on a really great first contribution to The Good Docs Project. Big thanks to the original release template authors, Tara Sweeney and Rachel Stainer, for giving Leigh such a strong foundation to build upon and for cooperating with building the resources file. We also want to thank the members of Team Dolphin, the template editorial team, and the template leads for all their support.

Check out the Release notes template in our templates GitLab repository!

Changelog template

The Changelog template, authored by community members Cat Keller and Deanna Thompson, is an excellent addition to The Good Docs Project’s template collection. The Changelog template is a high quality complement to our release notes template. Changelogs are often confused with release notes. They are both essential documents in software development for documenting and communicating product changes over time. However, there are several key differences between the two.

For example, Changelogs are written for a technical audience that wants a more comprehensive breakdown of what is going into a specific release, including detailed code changes. Release notes can be written for both a technical and non-technical audience who wants a more high-level description of new features and fixes for a release.

The Changelog template is Cat’s first template contribution to the project and Deanna’s second template contribution to the project. Both Cat and Deanna are members of the Team Alpaca Templates working group, with Deanna serving as co-lead of Team Alpaca. Cat and Deanna are also members of the community management team.

When asked about their paired writing process, Cat and Deanna shared their experiences:

The Changelog template was my first contribution to The Good Docs Project. As a new member with minimal experience in technical writing and the intricacies of changelogs, taking on a full template was intimidating. Luckily, I had the chance to work with Deanna, an amazing mentor, to develop this template. Through this experience, I gained valuable skills and learned so much about technical writing within a supportive community. I am grateful to everyone who helped with the Changelog template, from research to reviews. I hope people find it useful and informative.

— Cat Keller

Deanna adds:

Cat and I worked together to complete the changelog template project. Every week, we met to share our thoughts about best practices for building changelog and developing a template that software project team members can quickly adopt for their own applications. We did extensive research on the structure and content of a changelog through looking at changelogs from well-established open source projects.

I personally enjoyed working with another templateer on this project. It was great to put our heads together and exchange our ideas with each other. Our paired writing system works really well and I hope to work with another contributor soon.

— Deanna Thompson

This template is a great example of successful collaboration and our paired writing buddy system. The Changelog template is a part of the open source software community docs template pack. We feel strongly that this template will empower engineering teams, API developers, and open source maintainers to write effective changelogs for their own projects.

Congratulations and thanks to Cat Keller for a wonderful first contribution and to Deanna Thompson for another great contribution. We would also like to thank Rob Beg who was one of the original templateers on the project before Cat joined the project and who brought it a long way. Last but definitely not least, thanks to the members of Team Alpaca, the template editorial team, and the template leads for all the excellent feedback on this project along the way!

Check out the Changelog template in our templates GitLab repository!

Notice of license change to MIT-0

The Friendship templates release has one other big change. This release cycle, our project steering committee voted to change our templates repository license from Zero-Clause BSD to the International MIT-No Attribution license, most commonly known as MIT-0. This open source license applies to the templates in this release going forward.

Some of our main reasons for changing licenses include:

MIT-0 is a more widely recognized and popular open source license.
It includes documentation in its definition of what is covered under the license agreement.
It establishes a copyright claim for The Good Docs Project if needed.

Zero-Clause BSD and MIT-0 are similar to each other in scope and coverage, so the impacts from this change should be minimal. Like the BSD family of licenses, the MIT License is a permissive open-source software license with minimal restrictions of reuse. We have always opted for the no-attribution license in order to encourage the widest distribution possible for our templates. However, we strongly encourage the ethical attribution of our templates as much as possible.

Community news

During the Friendship release, our community continued to grow. We welcomed Michael Hungbo to the Project Steering committee! We are also happy to announce two new working groups; Team Penguin (a collaboration group for the DocOps Registry, UX and Outreach and the editorial teams) and our new Knowledge base group led by Melissa Mergner and Marat Yapparov. We are very excited to see new groups form and community members grow into leadership roles and thank them for all that they do!

DEI badge

Gitlab partnered with the Community Health Analytics in Open Source Software (CHAOSS) project to integrate GitLab with their DEI Project Badging program, which enables open source projects to build diverse communities. They highlight the work open source communities are doing to welcome and support new members by awarding DEI badges to open source projects. These badges are used to showcase commitment to improving and supporting diversity, equity, and inclusion in open source projects.

As a GitLab partner, The Good Docs Project was inspired to work closely with CHAOSS to create our own DEI Initiative and we are proud to announce that we have been awarded a bronze DEI badge from CHAOSS. Our reviewer from CHAOSS said:

It was really beautiful seeing how you are all creating inclusive spaces in your communities.

In order to earn this badge, we had to write a policy explaining our policies and procedures for improving diversity, equity, and inclusion in several different focus areas. Some of our favorite highlights from our new DEI policy are:

The Good Docs project is a global, open source community in which anyone can join. You don’t have to be a technical writer to join; you only need to care about documentation and want to educate and empower others to create high-quality documentation. If you care about docs, you’re welcome!
We hold monthly Welcome Wagon meetings for newcomers to provide an in-depth introduction to our project. In this meeting, newcomers learn about our project goals and mission, our working groups, and important community resources.
We provide opportunities for contributors to move into leadership roles. Our teams are open to anyone who is interested and who has contributed to the project for at least one month. Opportunities to become a working group lead or supporting teams are available for all major geolocations.
We work to prevent burnout in our community. We encourage all community members to prioritize work-life balance. We make accommodations for community members who need to step back from the project temporarily or permanently to focus on their family, work, or other personal matters. We encourage taking breaks by building in 3-week rest periods into our release cycles.
We mentor and formally train our community members about the core technologies needed to contribute to our project, such as Git, GitLab, and Markdown. Our community management team offers Git training workshops to members who are in need of additional skills in order to be able to contribute. These workshops lower the technical barrier to entry in our project and equalize the playing field so that anyone in the project can contribute.

You can read our full DEI policy on our Community and governance repository.

Tech Team

During the Friendship release, we changed the project’s communication platform from Slack to Discord. The successful migration to Discord was proposed by co-chair and Tech Team member, Michael Park, and lead by the Tech Team after gathering positive community feedback and approval from the Project Steering Committee (PSC). As our community continues to grow, it was important for us to archive and save project history while also keeping our overhead costs low. Discord also came with some additional benefits, such as the ability to better monitor entry into our communication platform and requiring everyone who joins the platform to agree to The Good Doc Project’s Code of Conduct. The migration went incredibly smoothly and we want to thank the Tech Team for successfully leading this migration!

Community managers

The Community managers continue to ensure our community is healthy, vibrant, and safe for all who want to participate. During the Friendship release, the Community Managers led in the creation and delivery of our DEI policy.

The Community managers also focused their efforts on creating an exit survey for The Good Docs Project. The goal of the exit survey is to provide an opportunity for contributors who have left or are leaving the community to share feedback about their overall experience, including positive feedback and feedback on areas where we can improve. Gathering this information would allow us to share successes, take note of trends in data, and address any pain points that contributors might have experienced.

Team Dolphin

During the Friendship release, our community grew quite a bit, especially in the EMEA region. As a result, Team Dolphin, which is one of the working groups that serves the EMEA region, nearly doubled in size. We’re excited that Team Dolphin has experienced so much growth and enjoy the energy coming from our new contributors. During this time, Elliot Spencer became the Team Dolphin Chronologue working group co-lead, joining Michael Hungbo.

Partnerships

Recently, a few tooling providers and other organizations have stated their interest to incorporate our templates into their products and processes and establish a more formal relationship with us. We see this as an exciting tipping point and validation of the value our templates and community bring.

To read about our exciting partnership with GitLab, see the the partnership announcment on the GitLab Open Source Partners page and our blost post, We are GitLab Open Source Partners.

We are also thrilled to share about our great partnership with JetBrains. As of recently, you can access The Good Docs Projects templates in JetBrains Writerside. To learn more, see our blog post, We are JetBrains partners.

A look ahead

A huge thank-you to all our contributors and collaborators on the Friendship release! With your great contributions, we can continue to grow a supportive, diverse, passionate, and fun-loving community.

Help us improve in the next release:

If you have 5 minutes and a project lined up: Use our templates! Every template has a survey link at the bottom, so let us know how it went.
If you have 10 minutes: Take our doc maintainers survey. We can prioritize work aids for content maintainers, if we understand their pain points.
If you have 2-3 hours per week: Feel free to share your documentation best practices as a contributor.

Blog Posts tagged with 'ROI'

Making a business case for documentation, post 8 - Calculate the ROI of documentation