This is number 4 of a five-part presentation:

• Writing About Writing — Technical Documentation
• Why Everything You’re Doing In Technical Writing Is (Probably) Wrong
• The Flying Car Era of Technical Writing Tools and Workflows
• An Example of git/Markdown Workflow
• The best part of using git and Markdown

In this section we see how few steps are required to be part of a distributed content workflow.

git Workflow

In its entirety, here’s what’s needed to contribute, once you’ve set up your git credentials with your repository host (which itself is only a few steps):

% git clone https://path.to/repository/subject.git
% cd subject/
% [edit README.md with favorite text editor or IDE]
% git add README.md
% git commit -m "Pithy comment about what I did here."
% git push

The takeaway from this is how straightforward the process is. No digging around cloud drives to find the active document being edited, avoiding all the copies attached to dozens of email threads (any or all of which have diverged from the master document).

Best of all, this is already the workflow used by the software development staff, those subject matter experts who are in demand to provide accurate updates to the documents.

A view with explanations, for those unused to git:

1. git clone makes a local copy of the central document repository.
2. cd repository jumps into the local copy, where the files and folders of the document repository can be seen.
3. [edit with favorite text editor or IDE] is how the information is updated. (More on that below.)
4. git add README.md stages changes made to the file README.md to the list of files to have their changes logged and placed under version control.
5. git commit -m "explanation" takes the explanatory note and the changes made to the staged files and rolls them up into a versioned commit, making a local backup which can be restored at any time.
6. git push takes the local copy and merges it with the copy on the central repository, mediating changes made by multiple authors. git asks for help if these changes overlap.

These steps don’t have to be memorized; there are programs with graphic user interfaces for git if point-and-click is more your style.

Markdown Workflow

Markdown is perhaps the most stark expression of the "good enough" ethic — what it does it does well, what it doesn’t do forces a contemplation on what’s truly needed in documentation.

Markdown enjoys wide adoption: it’s currently supported in software you’re using right now like Slack and Google Chat. Type this is a *good* idea and see what happens.

A short example of Markdown in action will illustrate:

Congratulations on having read to this point! It wasn’t easy to contemplate changes to your workflow, even with the promise of pushing responsibility of information-gathering down to those in the know, but you made it!

This is a subject heading

This is some pithy explanation.

This is a second-level heading. Six levels are supported.

• Bulleted and nested lists are trivial to make.
• Numbered lists are automatically calculated.
  1. Like this.
  2. Notice each entry begins with 1. but the output appears 1, 2, 3…
  3. Nesting is done simply by indenting with tabs.

Tables	Are	Quite	Basic
But they provide	the basic tabular	structure and are	easy to read.

The Markdown to create the above:

| Congratulations on having read to this point! It wasn't easy to contemplate changes to your workflow, even with the promise of pushing responsibility of information-gathering down to those in the know, but you made it! |
|:---|

# This is a subject heading

This is some pithy explanation.

## This is a second-level heading. Six levels are supported.

* Bulleted and nested lists are trivial to make.
* Numbered lists are automatically calculated.
	1. Like this.
	1. Notice each entry begins with <code>1.</code> but the output appears 1, 2, 3...
	1. Nesting is done simply by indenting with tabs.

| Tables | Are | Quite | Basic |
|:---|:---|:---|:---|
| But they provide | the basic tabular | structure and are | easy to read. |

The Markdown to create the above:

	```markdown
	(the Markdown is here)
	```

Markdown doesn’t have any built-in table of contents (although the primary git repository provider does offer that functionality), it doesn’t do more than basic text formatting, doesn’t provide fine-grained control over content display, and certainly doesn’t have the bells and whistles offered by dedicated content management systems.

These downsides are offset by the advantages of simplicity and efficiency. What’s "good enough" for your documentation? What do your customer consumers actually need? If it isn’t clear, well-formatted information it might be time to reassess the priorities behind your creation and updating of technical documentation.

There are legitimate needs for pixel-level control, but few of them, and in my decades of experience those perceived needs are overblown when balanced against the need for fast updates of topical information.

Markdown can be the input to a dedicated workflow to create more traditional document formats: whether it’s using pandoc directly, using Markdown to drive the powerful typesetting engine ConTeXt, or to generate enterprise-wide reports with Markdown R. There are many "flavors" of Markdown and even more ways these fit into mature workflows.

And we haven’t even gotten to the best part of using git and Markdown.