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!
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:
Links
- Google Style Guide
- Microsoft Style Guide
- Write The Docs / Documentation Guide: Style Guides
- A11Y Style Guide
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!
Links
- Stylelint - From the site: "A mighty, modern linter that helps you avoid errors and enforce conventions in your styles."
- Atom IDE Plugin: Google Style Guide word list linter
- textlint: The pluggable linting tool for text and markdown
- Blog Post: Introducing Vale, an NLP-powered linter for prose
- proselint: A linter for prose
- Schematron - Rule-based validation language expressed in XML
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:
Links
- Examples of "Awesome" README.md files!
-
GitHub special profile README how to, by Monica Powell
- Example: My profile, which used Monica's example as a template.
- Example: My profile README source repo
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.
Links
- Manifesto from The Good Docs Project on cross-domain management of glossaries
- Microsoft Style Guide: A-Z word list and term collections
- Google Style Guide: Word list
- What should a glossary entry look like? - some jump points.
Misc resource links
- Docs as Code - From the WTD site: "Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code: Issue Trackers, Version Control (Git), Plain Text Markup (Markdown, reStructuredText, Asciidoc), Code Reviews, Automated Tests..."
- Just Not Sorry chrome extension for GMail: Helps avoid self-deprecating language when writing emails.
- How to Make a Documentation Culture: Blog Post
- Information Architecture: For the Web and Beyond book, referenced and used by people who were attending the session
- Axe Linter, by Deque - From the site: "Powered by Deque Systems, axe Linter helps you automatically find and fix accessibility issues. Axe Linter analyzes the changed or added code of your GitHub pull requests, reports issues and intelligently requests changes for common issues- all before your pull request gets reviewed and the code gets merged."
Latest comments (0)