# ASCIIDOC CONVERSION MATRIX

> Standard operating procedures for converting chaotic thoughts into structured AsciiDoc files for the tech documents.

- Canonical: https://www.alpacamango.com/docs/asciidoc-conversion-matrix
- Author: El Capitano. S. Robinson
- Published: 2024-01-15 · Updated: 2026-08-09
- Topics: Meta, Documentation

## 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](url)

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)*