Skip to main content

Documentation Standards

How to write and maintain documentation for Almafrica.

Principles​

  1. Clear and concise - Get to the point quickly
  2. Audience-aware - Write for the reader's level
  3. Up-to-date - Update docs with code changes
  4. Actionable - Include concrete steps and examples
  5. Searchable - Use consistent terminology

Document Types​

TypePurposeLocation
GuideHow-to instructionsdocs/guides/
ReferenceLook-up informationdocs/references/
ArchitectureSystem designdocs/architecture/
RunbookOperational proceduresdocs/runbooks/
PRDProduct requirementsdocs/product/prd/

Formatting Standards​

Markdown​

  • Use ATX-style headers (# Header)
  • Include table of contents for long documents
  • Use code fences with language tags
  • Limit line length to 100 characters where possible

Headers​

# Main Title (H1) - One per document

## Section (H2)

### Subsection (H3)

Lists​

- Unordered item
- Another item
  - Nested item

1. First step
2. Second step
3. Third step

Code Blocks​

// Always include language tag
const example = "code";

Tables​

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |
[Link text](./relative-path.md)
[External link](https://example.com)

Writing Style​

Voice​

  • Use active voice: "Run the command" not "The command should be run"
  • Be direct: "Do X" not "You might want to consider doing X"
  • Stay neutral: Avoid jargon and assumptions

Terminology​

  • Use Glossary terms consistently
  • Define acronyms on first use
  • Avoid ambiguous terms

Code Examples​

  • Include complete, runnable examples
  • Add comments for clarity
  • Show expected output

Document Structure​

Standard Template​

# Title

Brief introduction (1-2 sentences).

## Overview (optional for long docs)

More detailed context if needed.

## Section 1

Content...

### Subsection

More content...

## Section 2

Content...

## Related Documents

- [Related doc 1](../references/glossary.md)
- [Related doc 2](../guides/troubleshooting.md)

Maintenance​

When to Update​

  • New features added
  • Breaking changes made
  • Common questions arise
  • Documentation inaccuracies found

Review Schedule​

  • Quarterly review of all docs
  • Update on each release
  • Remove outdated information

File Naming​

  • Use lowercase with hyphens: quick-start.md
  • Be descriptive: api-endpoints.md not api.md
  • Match type: *-guide.md for guides

Best Practices​

Do​

  • Include code examples
  • Link to related documents
  • Update with code changes
  • Use consistent formatting

Don't​

  • Duplicate information
  • Leave outdated content
  • Use unclear headings
  • Assume reader context

Templates​

Guide Template​

# [Feature/Task Name]

Brief description of what this guide covers.

## Prerequisites

- Requirement 1
- Requirement 2

## Steps

### Step 1: [Action]

Description and code:

```bash
command --option

Step 2: [Action]​

...

Verification​

How to verify it worked.

Troubleshooting​

Common issues and solutions.


### Runbook Template

```markdown
# [Procedure Name]

Purpose of this runbook.

## When to Use

Situations that require this procedure.

## Prerequisites

- Access required
- Tools needed
- Backup status

## Steps

### Step 1: [Action]

```bash
command

Expected output.

Step 2: [Action]​

...

Verification​

How to confirm success.

Rollback​

How to undo if needed.

Contacts​

Who to contact for help.