Intro

The Good Docs Project (TGD) had a session table on Writing Day during the Write The Docs 2020 - Portland virtual conference. I wanted to write up a debrief on all the cool links and topics that were shared during the session. The table started as discussions around TGD templates repository on GitHub.

If any of these ideas excite you, then consider [joining us at The Good Docs Project!] (https://thegooddocsproject.dev/contact.html)

About The Good Docs Project

From The Good Docs Project (TGD) homepage:

“Every project deserves a minimum level of Good Docs that help users understand and solve problems with your product. But it can be really hard to know where to start or what to write. How do you structure docs? What does a docs website look like? How do I keep docs consistently formatted? The list of questions far outweigh the answers.

That’s where The Good Docs Project fits in. Our open-source Minimum Viable Docset (MVD) will help you create a baseline set of Good Docs using a suite of templates.”

Erin McKean also did a Write The Docs meetup presentation on the project:

Style Guide

How do you write a style guide for your project or organization which ideally is just a light wrapper over an existing style guide? TGD project is working on a template as a place for people to get started:

Converting TGD Templates to Your Favorite Formats

I opened a GitHub issue with thoughts around using Pandoc as a tool to convert TGD templates into wanted formats:

Linters

Linters can be implemented in documentation projects in order to analyze and catch issues automatically. This can help maintainers of projects, contributors, and ultimately empower anyone to write better docs.

They can help with:

  • Grammar and spelling
  • Inclusive language
  • Helping enforce style guides
  • Validating proper file format and best practices (markdown, rst, etc.)
  • And more!

The README.md file: Templates and resources

When a new repository is created, usually one file is crucial: the README (often README.md or README.rst in code repositories). It’s the first thing that greets people to your project, and can be what sparks interest in potential users or contributors.

GitHub and GitLab don’t have templates to choose from, by default, but merely give the option to initialize a file with a single header referencing the project name. Perhaps TGD could have example README templates, and also suggest feature requests to GitHub/GitLab for including optional README templates at initialization of project repositories?

For example, TGD has a repository that is missing a README, and could make use of it!

An issue has been opened here to track this:

Glossary: Word list and term collections

We are kicking off a pilot to define best practices for cross-domain management of glossaries. We are focusing on the spatial domain, and drawing on volunteers from communities associated with spatial standards, ISO standards, open source spatial projects, schema design, documentation and metadata management, and tech writing.