Skip to main content

Markdown and Documentation

Learning Objectives​

By the end of this lesson, you will be ableable to:

  • Use Markdown to write clear, structured, and maintainable technical documentation.
  • Write READMEs, lesson files, and lab notes using a consistent style.
  • Apply documentation best practices to your Flow Initiative work.
  • Use documentation as a communication tool for teammates and reviewers.

Introduction​

Markdown is the common language of modern technical documentation. It lets you write plain text that is easy to read on GitHub and easy to render on sites like Docusaurus.

In the Flow Initiative, Markdown is not an optional formatting layer. It is the primary medium for:

  • curriculum lessons,
  • lab notes,
  • READMEs, and
  • public‑goods documentation.

Good Markdown is clear, consistent, and focused on the reader’s workflow, not your personal style.

What Markdown Is (and Is Not)​

Markdown is:

  • A lightweight markup language for formatting text.
  • Designed to be readable even in its raw form.
  • Widely used in GitHub, Git, and documentation tools like Docusaurus.

Markdown is not:

  • A design tool.
  • A replacement for thinking.
  • A reason to ignore clarity and structure.

You are not “learning Markdown” for its own sake. You are learning it as a tool to explain and share your work.

Why Markdown Matters for Engineers​

Engineers need documentation that:

  • Scales with the code,
  • Lives in the same repository,
  • Is version‑controlled, and
  • Is easy to read and search.

Markdown supports all of these:

  • You can commit .md files alongside .py, .rs, .js, and .toml.
  • You can diff and review changes.
  • You can render them in GitHub, Docusaurus, or your portfolio.

This is especially important for African‑centric engineering, where clear, searchable docs reduce the need for synchronous explanations.

Basic Markdown Syntax​

You do not need to memorize everything. You need patterns that you can reuse.

1. Headings​

Use headings to structure your document:

# Page title

## Section

### Sub‑section
  • # and ## create large, important headings.
  • ### and lower create sub‑sections.

2. Text Formatting​

  • Bold with **bold**.
  • Italic with *italic*.
  • inline code with backticks.

Use bold and italics sparingly to emphasize meaning, not decoration.

3. Lists​

Unordered list:

- Item one
- Item two
  - Nested item

Ordered list:

1. First step
2. Second step

Use lists to organize details so they are easy to scan.

4. Code Blocks​

Use fenced code blocks:

```python
def example():
    return "Hello"

Always specify the language (e.g., `python`, `rust`, `javascript`). This enables syntax highlighting and makes the code easier to read.

### 5. Links and Images

Links:

```md
[Link text](https://example.com)

Images (when supported):

Use meaningful link text, not just “click here.”

Documentation Best Practices​

Good documentation is not just well‑formatted; it is useful.

1. Write for the Reader​

  • What problem does the reader need to solve?
  • What do they need to know right now?
  • What is the next step?

Put the most important information at the top, not buried in the middle.

2. Use a Consistent Style​

Across the Flow Initiative, aim for:

  • Short, direct sentences.
  • Active voice.
  • Clear examples.
  • Minimal jargon, or explain jargon briefly.

This makes your docs easier to read and maintain.

3. Separate “Why” from “How”​

Structure sections like:

  • Why: What problem does this solve?
  • How: How do I use it?
  • Examples: Show before tell.

This pattern helps readers understand the context before the details.

4. Keep Examples Minimal but Real​

  • Use small, concrete examples.
  • Avoid “toy code” that does not reflect real use cases.
  • Use examples that match your current track (e.g., blockchain, AI/ML).

5. Version and Clarify​

  • If something is version‑specific (e.g., Flow SDK v0.3), state it.
  • If a step only works in a certain environment, note it.

This prevents confusion later.

How Flow Uses Markdown​

In the Flow Initiative monorepo, Markdown is used in:

  • Curriculum — lesson files in curriculum/.
  • Knowledge‑base — articles and research summaries.
  • Labs — instructions, notes, and reflection.
  • Website — Docusaurus pages that render these files.

When you write a lesson, a note, or a README, you are contributing to a shared documentation system that supports:

  • onboarding,
  • teaching, and
  • project maintenance.

READMEs Are First‑Class Documentation​

For labs and projects, the README.md is the first place a reader will land. Treat it as a mini‑guide, not a footnote.

A good README answers:

  • What is this?
  • Why does it exist?
  • How do I run it?
  • Where can I learn more?

Structure it with clear sections:

# Project Name

## What it does

## How to run it

## Example usage

## Next steps or questions

Practical Exercises​

Exercise 1: Write a README for a Lab​

Pick one lab from your current track and write a README.md for it:

  • State the problem it solves.
  • Explain how to run it step by step.
  • Add one small example of expected output.

Exercise 2: Turn a Lesson into a Markdown Note​

Choose a lesson you have completed and write a short Markdown note that:

  • Summarizes the key idea in 3–5 lines.
  • Includes one example.
  • Lists 3–5 questions you still have.

Exercise 3: Style Review​

Take an existing Markdown file (your own or from the repo) and:

  • Check heading hierarchy.
  • Convert long paragraphs into shorter ones and lists where possible.
  • Add a code block where a snippet is implied but not shown.

Self‑Assessment​

Rate yourself from 1 to 5:

  • I can write clear, structured Markdown.
  • I can write a useful README for a lab or project.
  • I can use examples to explain ideas.
  • I can keep Markdown simple and focused on the reader.

Action item: improve one README or lesson‑style note this week and commit it to the Flow repo.

Next Steps​

  • Read 02-version-control.md next to see how Markdown documentation lives alongside Git history.
  • Use Markdown for every lab, article, and contribution in the Flow Initiative.
  • Treat documentation as part of your engineering output, not an afterthought.

Resources​

  • Markdown syntax and best practices for technical writing.
  • Engineering documentation and README‑writing patterns.
  • Docusaurus Markdown and MDX documentation guides.

Video​

This lesson teaches Flow Initiative trainees to use Markdown as a powerful, simple tool for writing and sharing engineering‑grade documentation across the monorepo and beyond.