Skip to content

Writing Documentation

Good documentation is what makes this wiki worth using. This page covers three things: what makes documentation good, what should (and shouldn't) go in the wiki, and how to format pages so they're consistent with the rest of the site.

What Defines "Good" Documentation?

Good documentation is more than just a "useful information repository". A useful guide to writing good documentation consists in it being able to answer the following questions:

  • What is the thing?
  • What does the thing do?
  • Why or for what would you use the thing?
  • How do you use the thing?

Usability and accesibility should always be a priority, so keep in mind the following points when writing documentation:

  • Write for someone who knows less than you. Assume the reader is capable but doesn't have your context. Spell out acronyms the first time you use them.
  • One page, one topic. If you find yourself writing "as a side note" or "unrelated, but," that content probably belongs on its own page.
  • Show, don't just tell. A short example, command, or screenshot usually explains more in less space than a paragraph of prose.
  • Keep it current. A wrong page is worse than no page — if a process changes, update the doc in the same pull request.
  • Write in plain language. Prefer short sentences and everyday words over jargon; when jargon is unavoidable, define it once.
  • Front-load the point. Put the most important information first, and leave background or edge cases for later. Most readers are scanning, not reading top to bottom.

This is a living document

If you find yourself teaching someone a documentation habit that isn't listed here, add it! See our contribution guide for technical information.

Documentation should consider any difficulties that a new user will come across when learning, and be able to answer them throughout the read. In essence, an "excellent" documentation is one that takes you from absolute beginner to somewhat competent and provides enough extra resources to open the door to the rabbit hole, including:

  • A brief explanations about the technology, it's processes and any standards associated with it.
  • An explanation on why, how and/or for what you would use this technology, including a brief look into it's configuration.
  • Useful links to external references, including fundamental knowledge and any other simplifier you find useful.

It is not necessary to be an expert in something to be able to write competently about it. Consider using your own learning experience as a reference when presenting information.

Content Guidelines

Documentation should be accessible. Without a clear structure or order to ideas, it is impossible for documentation to be as useful to others as it would be to you. It is also important to consider that not all information belongs in the wiki, and not everything belongs in the same place. A few general rules:

  • General knowledge goes here; client-specific secrets don't. Processes, standards, and how-tos belong in the wiki. Credentials, client contracts, and anything confidential belong in their proper access-controlled location; link to it if needed, NEVER paste it here.
  • Every page needs a home. Before creating a new page, check whether it fits into an existing section. If it doesn't fit anywhere, that's a sign we might need a new section, not a stray page.
  • File and folder names are lowercase, hyphen-separated. Do network-assessment-checklist.md, not Network Assessment Checklist.md.
  • Both languages, when possible. Every page should exist in English and Spanish. If you can only write one right away, add the other as a follow-up.
  • Don't duplicate, link. If the information already lives on another page, link to it instead of copying it. Duplicated content drifts out of sync.
  • Someone else should read it before it merges. A second pair of eyes catches unclear steps that make perfect sense to the person who wrote them. Always ask for external revision.

Format Specifications

These are mechanical rules that help keep every wiki page looking and behaving in the same way.

Use this document as reference

This exact document is a good reference to use for your own writing. You can read it directly in raw format to see the unrendered page.

Metadata

Every page should start with a front matter block, starting and ending with three dashes (---) and following a key:value pair format:

---
title: Page Title
description: One-sentence summary shown in search results and previews.
authors:
  - Author 1
  - ...and maybe Author 2?
date:
  created: When this document was first written, in YYYY-MM-DD format.
  updated: When this document was last updated, in the same format.
lang: Language tag, depending if it's in English (en) or Spanish (es).
---

Headers

Markdown (the language the wiki pages are written in) uses headers to organize content throughout the page. Use a single # (H1) for the page title, then ## and ### to build the hierarchy. Don't skip levels; a ### shouldn't appear directly under a #.

Text Formatting

Style Syntax Result Guideline
Bold **text** text Key terms, titles, button names, and first mentions of important concepts.
Italic *text* text Subtle emphasis within a sentence to change the reader's tone or stress a specific word to avoid ambiguity.
Inline code `code` code Binaries and executable programs in a user's computer, environment variables.
Angled brackets in code `<text>` <text> Values to be replaced in a command, like an IP address or user credential.

Code Blocks

Use code blocks to showcase code, commands and terminal-specific input/output. Always specify the language for accurate syntax highlighting:

```bash
git status
```

Admonitions

Use admonitions to call out information without breaking the flow of the page:

!!! tip "Optional title"
    Content goes here, indented four spaces.

Common types: note, tip, warning, danger, example.

When writing, you will often come across a need to link to both internal and external content.

For internal content, use relative links for other wiki pages: [Contributing](contributing.md). Absolute and relative paths are valid, but consider that all paths start from the docs/ directory, instead of the "real" root of the project.

For external references, you can link inline when appropiate, but it is a good idea to add a "Further Reading" section when the documentation may need further references. Keep in mind the following best practices:

  • Organize by relevance. Group links by topic or purpose (e.g., "Official Documentation," "Tutorials," "Community Resources").
  • Use descriptive text. Avoid linking bare URLs, instead provide context about what the resource contains, for example: [Forgejo Documentation - Branch Protection](https://forgejo.example.com) instead of just a URL.
  • Archive external links. use services like the Wayback Machine or Archive.today to create permanent snapshots of important external resources. Include the archive link as a fallback in a reasonable format like [text](link) ([archive](archive-link)).
  • Avoid over-linking. too many external links can overwhelm readers, so prioritize the most valuable resources.

Images

In our project directory, we keep a separate assets/ directory which replicates the documentation structure. Keep related images in a directory with the same name as the documentation, nested under its corresponding level.

wiki/
└ docs/
  └ assets/
    └ getting-started/
      └ writing/
        └ Images for this specific document go here!