Brian Dominick briandominick

Imagine a schema for defining expected directory/file structures for your applications.

Define it all in YAML, then use a proper library to:

validate an existing path structure against your schema
generate model folder/file trees in arbitrary or logical order
document your expected path structure based on properties of each dir/file key

Take a look at the following example schema.

Why Use AsciiDoc for Software Documentation

I have now spent a decade convincing engineers and technical writers to use AsciiDoc markup for as much of their product documentation as is humanly possible. Few if any of them have regretted adding AsciiDoc to their skillset or switching to it entirely, so now I hope to make the case for a general audience.

This article collects the arguments I have long used to help writers and software developers see that AsciiDoc is far and away the optimal solution to nearly all documentation matters beyond API docs (where more structured approaches are called for).

For anyone using docs-as-code workflows and free, open-source software, the main competitor for AsciiDoc is Markdown, which many developers love and swear by. For this reason, I will compare/contrast AsciiDoc and the collective flavors of Markdown.

Software Documentation Tooling Decision Guide

The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.

I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.

Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.

Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.

Using a Spellcheck Template with Vale

Place or recreate the accompanying spellcheck.golang.yaml file in your project directory.

Note
You will probably want to modify the AI Agent Instructions to match how you handle spelling exceptions.

Run an altered version of your typical vale command:

vale --filter='.Name=="Vale.Spelling"' --output=path/to/spellcheck.golang.yaml README.adoc > spellcheck.yml

	{
	"Pet": {
	"type": "object",
	"required": [
	"name",
	"photoUrls"
	],
	"properties": {
	"id": {
	"type": "integer",