ASCIIDOC CONVERSION MATRIX

Standard Operating Procedures for Technical Documentation#

Author: El Capitano. S. Robinson Classification: Meta-Documentation Purpose: Organizational excellence through structured chaos

The Problem We're Solving#

Converting chaotic, stream-of-consciousness technical thoughts into structured AsciiDoc files is 47% less painful than before, thanks to this matrix.

Conversion Workflow#

Stage 1: Capture Phase#

Dump all your thoughts into a text file. Grammar? Optional. Coherence? Aspirational.

raw brain dump:
- llamas are fast
- style is important???
- mangoes attacked sector 7 again wtf
- wool physics unclear
- sarcasm is a force multiplier

Stage 2: Organization Phase#

Sort your chaos into logical groups:

1. Overview — What is this about?
2. Technical Details — How does it work?
3. Examples — Show, don't tell
4. Edge Cases — When does it break?
5. Safety Notes — What not to do?

Stage 3: Markup Phase#

Convert to AsciiDoc syntax:

= Document Title

== Section Heading

=== Subsection

* Bullet point 1
* Bullet point 2

[source,code]
----
code example here
----

.Table Example
|===
| Header 1 | Header 2
| Data 1 | Data 2
|===

Stage 4: Review Phase#

• Check for consistency in tone
• Verify all technical claims are defensible
• Ensure examples actually work
• Remove 80% of emoji and exclamation marks

The AsciiDoc Syntax Quick Reference#

MarkdownAsciiDocUse Case

# Heading

= Title

Document title (one per file)

## Heading

== Section

Major sections

### Heading

=== Subsection

Subsections

bold

*bold*

Emphasis

code

`code`

Inline code

> quote

> quote

Block quotes

link

link:url[link text]

Hyperlinks

Checklist Before Publishing#

• Document has a clear title
• All technical claims verified
• Examples tested
• Typos eliminated (mostly)
• Tone is consistent
• Edge cases documented
• Safety warnings present

Common Pitfalls#

1. Over-explaining simple concepts — Trust your readers
2. Under-explaining complex ones — Err on the side of clarity
3. Inconsistent terminology — Pick a term and stick with it
4. No examples — Code speaks louder than prose
5. Ignoring edge cases — Document the weird stuff

See also: PROTOCOL: TECHNICAL WRITING EXCELLENCE (Coming Soon)