briandominick

API Documentation Decision Matrix

The following flow diagram is intended to help you quickly decide how to document a REST API.

There is a Glossary and other primer information following the graphic.

Glossary

briandominick

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.

briandominick

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.

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.

briandominick

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

briandominick

Setting up Bibisco on Ubuntu 19.04

(tested on PopOS 19.04)

1. Download linux archive from Bibisco.

2. Move files to better path.

   sudo mv ~/Downloads/bibisco-blah-blah/ ~/opt/bibisco

briandominick

# Fusuma makes Linux touchpads better
# See https://github.com/iberianpig/fusuma
swipe:
  3:
    left:
      command: 'xdotool key alt+Right'
    right:
      command: 'xdotool key alt+Left'
    up:
      command: 'xdotool key super'

briandominick

# See README.adoc

briandominick

See README.adoc

briandominick

Documentation Engineering Consulting Agreement