Markdown Documentation Foundation

Purpose

This document defines a simple foundation for writing project, research, technical, and decision documents in Markdown.

Markdown is the canonical source format. Other formats, such as HTML or PDF, may be generated from it, but the Markdown document remains the primary version that should be edited, reviewed, and versioned.

Note: Treat generated HTML and PDF files as disposable outputs. Review and change the Markdown source instead.

The goal is to keep documents clear, consistent, easy to maintain, and suitable for both informal project work and formal sharing.

Core Principles

1. Markdown is the source of truth

Each document should be written and maintained as a Markdown file. Generated versions are outputs, not the original document.

2. Documents should be readable without rendering

A Markdown document should still be understandable when viewed as plain text. Avoid relying on formatting tricks that only work after rendering.

3. Structure comes before styling

Documents should focus on clear headings, consistent sections, readable paragraphs, and well-organized references. Visual styling should be handled separately.

4. Sources must be traceable

Every important external claim, standard, article, documentation page, paper, or project should be listed in the references section.

5. Decisions should be explicit

When a document recommends or chooses something, the decision should be clearly separated from the context, alternatives, reasoning, and consequences.

Document Metadata

Each document should start with frontmatter that describes the document.

---
title: "Document Title"
author: "Author Name"
status: "draft"
version: "0.1.0"
date: "YYYY-MM-DD"
citation-style: "IEEE"
---

Recommended metadata fields

Field	Purpose
title	Human-readable document title
author	Main author or owner of the document
status	Current state, such as draft, review, accepted, or archived
version	Document version
date	Document date
citation-style	Reference style used in the document

General Document Structure

Use this structure for most project, research, and technical documents.

# Document Title

## Summary

## 1. Introduction

## 2. Context

## 3. Requirements

## 4. Options Considered

## 5. Decision or Recommendation

## 6. Rationale

## 7. Consequences

## 8. Risks and Trade-offs

## 9. Conclusion

## References

Not every document needs every section. Short documents may omit sections that do not add value.

Section Guidelines

Summary

Give a short overview of the document. A reader should understand the purpose and outcome of the document from this section alone.

Introduction

Explain what the document is about and why it exists.

Context

Describe the background, current situation, problem, or project environment.

Requirements

List the important requirements, constraints, goals, or non-goals.

Options Considered

Describe possible approaches. Each option should include its strengths and weaknesses.

Decision or Recommendation

State the chosen option or recommended approach clearly.

Rationale

Explain why the decision was made. This section should connect the decision back to the context, requirements, and trade-offs.

Consequences

Describe what changes because of the decision. Include both positive and negative consequences.

Risks and Trade-offs

List known risks, limitations, open questions, and future concerns.

Conclusion

Summarize the final outcome and any next steps.

References

List every source used in the document.

Architecture Decision Record Structure

Use this shorter structure for focused architecture or project decisions.

# ADR-000: Decision Title

## Status

Draft | Proposed | Accepted | Superseded | Rejected

## Context

## Decision

## Rationale

## Consequences

## References

An ADR should explain one decision. If a document contains multiple unrelated decisions, split it into multiple ADRs.

Source and Citation Style

Use IEEE-style numbered references by default.

In the text, cite sources using numbers in square brackets:

This pattern is commonly used in technical documentation [1].

In the references section, list sources in the order they appear:

## References

[1] Organization, “Page title,” Website or Publisher, Accessed: Jun. 2, 2026. [Online]. Available: https://example.com

Reference Formats

Website or documentation page

[1] Organization, “Page title,” Website Name, Accessed: Month Day, Year. [Online]. Available: URL

GitHub repository

[1] Author or Organization, “Repository name,” GitHub, Accessed: Month Day, Year. [Online]. Available: URL

Paper, article, or publication

[1] A. Author and B. Author, “Title of paper,” Publication or Conference Name, year.

Standard or specification

[1] Organization, Standard Number, “Standard title,” year.

Writing Rules

Use clear headings

Headings should describe the content that follows. Avoid vague headings such as “Other” or “Extra.”

Prefer short paragraphs

Long paragraphs are harder to scan. Use short paragraphs that each explain one idea.

Separate facts from opinions

Facts should be supported by sources when needed. Opinions, recommendations, and assumptions should be clearly written as such.

Make assumptions explicit

If a document depends on an assumption, write it down.

Assumption: The Markdown document remains the canonical source, and generated outputs are not edited directly.

Record trade-offs honestly

Avoid presenting a decision as perfect. Good documents explain what is gained and what is lost.

Keep terminology consistent

Use the same term for the same concept throughout the document.

Avoid unnecessary implementation detail

The document should define the foundation, structure, and rules. Specific tooling and rendering pipelines can be built on top of this foundation later.

Recommended File Organization

docs/
  decisions/
  reports/
  research/
  templates/
  assets/

decisions/

Architecture Decision Records and project decisions.

reports/

Formal reports, summaries, and longer documents.

research/

Research notes, comparisons, findings, and source-based investigations.

templates/

Reusable document templates.

assets/

Images, diagrams, and other supporting files referenced by documents.

Base Template

---
title: "Document Title"
author: "Author Name"
status: "draft"
version: "0.1.0"
date: "YYYY-MM-DD"
citation-style: "IEEE"
---

# Document Title

## Summary

Write a short summary of the document.

## 1. Introduction

Explain the purpose of the document.

## 2. Context

Describe the background and problem.

## 3. Requirements

List the important goals, constraints, and non-goals.

## 4. Options Considered

Describe the possible options.

## 5. Decision or Recommendation

State the chosen direction.

## 6. Rationale

Explain why this direction was chosen.

## 7. Consequences

Describe the effects of the decision.

## 8. Risks and Trade-offs

Describe known risks, limitations, and trade-offs.

## 9. Conclusion

Summarize the result.

## References

[1] Organization, “Page title,” Website or Publisher, Accessed: Month Day, Year. [Online]. Available: URL

ADR Template

---
title: "ADR-000: Decision Title"
author: "Author Name"
status: "draft"
version: "0.1.0"
date: "YYYY-MM-DD"
citation-style: "IEEE"
---

# ADR-000: Decision Title

## Status

Draft

## Context

Explain the situation and problem.

## Decision

State the decision clearly.

## Rationale

Explain why this decision was made.

## Consequences

Describe the results, trade-offs, and follow-up work.

## References

[1] Organization, “Page title,” Website or Publisher, Accessed: Month Day, Year. [Online]. Available: URL

Final Rule

Write documents so they are useful first as Markdown, then reusable in other formats later.

The Markdown file should contain the structure, meaning, sources, and decisions. Rendering and presentation can be added on top without changing the foundation of the document.