The nice thing about standards is that you have so many to choose from.

[This blog post has time travelled. It is from a previous blog that predates the very existence of this one.]

Being the Internet, I should probably attribute that to either Mark Twain or Abraham Lincoln (and in fact, Google and Bing give dozens of people who supposedly said it), but it's from Andrew Tannenbaum's Computer Networking textbook that I used when I was in college, and seems to be original with him.

My "standard of the day" is Markdown. If you're not familiar with it, it's basically "HTML lite" -- a way of writing documentation by specifying the function, rather than the format, of each textual element, and then it gets magically massaged into something that looks good. It's very lightweight, very broadly supported, and you can learn it in about fifteen minutes (for example, look here: https://www.markdownguide.org/cheat-sheet/). It makes up the baseline documentation format for many blog tools (including this one, although I haven't figured out how to turn it on, yet), GitHub, most modern Wikis, and the internal documentation systems of both Android and Apple. Apple's recent WWDC had a number of sessions on their flavor, called DocC, that's basically the future of formatting for them (even for in-code comments, which is pretty slick, actually). As a baseline documentation language, it serves roughly the same function for technical writers as C does for developers: what you use might not be exactly the same, but you can bet it's heavily influenced by it.

But--as with C-like languages--"flavor" is the right word. John Gruber invented it in 2004 or so, and the basics haven't changed much. But all it really does is give you formatting of lists in various ways, headings and outlines, paragraphs, internal and external links, and the sort of basic "emphasis" technologies like italics and boldface.

Which is actually sort of a nice feature: it basically removes the emphasis from formatting back to content. But there's a lot of ways of presenting information, some of which are pretty standard: footnotes, references, tables, various types of "code" blocks, and the like. So lots of systems have "extended" it in various ways, and not all of those are compatible with each other. So when someone tells you to write in Markdown, "Which one?" is not an unreasonable question.

Probably the de-facto winner in the Markdown war is "Github Flavored Markdown," (https://github.github.com/gfm/) just because of its centrality to one of the most common developer tools on the web. So if that same someone responds to your question with "Uh, I don't know?" GFM is a good baseline assumption. Github also has a backend system called Github Pages that allows you to add structured Markdown files to your Github projects (or just to your Github account), and it will render them using its "Jekyll" rendering engine.

Looking into technologies for a potential writing project, a former boss of mine pointed me at Docsify (https://docsify.js.org/#/), which is a replacement for Jekyll that does a little more stuff: in particular, it supports custom sidebars/guides, renders the markdown into HTML on demand (rather than requiring a compiling step), and is also supported by Github Pages. Even better, if you fuss with it a little bit, you can use Mermaid (https://mermaid-js.github.io/mermaid/#/) in code blocks, which gives you a near-magical ability to create the various charts (Gantt, Flow, Sequence Diagram, etc.) that make up the technical documenter's nightmares, using a language so simple you can teach it to pretty much anybody who understands what the charts are supposed to represent.

I've been playing with this a bit on a GitHub project for terrain generation in the Unity game engine. You can see the documentation as it gets written here: https://ckempke.github.io/UnityTerrainGeneration/#/

[Update, a year later].  Docsify proved to be a little too "strict" in its formatting options to allow the flexibility I was looking for, so I currently use MkDocs, which is a more advanced version of the same sort of markdown->HTML site generator. In fact, you're looking at it now, since this blog is rendered with it.