Amanoba Logo
Back to Course

Documentation basics

Day 20 of 30 · Generative AI 2026: Build AI Apps and Agents

One-liner: Write clear setup and usage docs that reduce support.
Time: 20 to 30 min
Deliverable: User Guide and Dev Setup Doc

Learning goal

You will be able to: Write short documentation that helps users succeed quickly.

Success criteria (observable)

  • Docs include setup, usage, and troubleshooting.
  • Each section is under 10 lines.
  • The first success path is described.

Output you will produce

  • Deliverable: User Guide and Dev Setup Doc
  • Format: Two markdown docs
  • Where saved: Repo and course folder notes

Who

Primary persona: Digital nomad writing docs for a small product Secondary persona(s): Users who need quick guidance Stakeholders (optional): Collaborators

What

What it is

Two short docs, one for users and one for developers. They explain how to get started and what to do if something fails.

What it is not

It is not a full manual or a long knowledge base. It is a concise starting point that reduces support.

2-minute theory

  • Good docs reduce support requests and churn.
  • Short docs are more likely to be read.
  • Clear first success steps drive activation.

Key terms

  • User guide: A short guide for new users.
  • Setup doc: A short guide to run the project locally.

Where

Applies in

  • README or docs folder
  • Onboarding links

Does not apply in

  • Marketing pages only

Touchpoints

  • README
  • Help link
  • Support replies

When

Use it when

  • You have a working MVP
  • You plan to onboard users

Frequency

Update after major changes

Late signals

  • Users ask the same setup questions
  • Support is overloaded

Why it matters

Practical benefits

  • Faster onboarding
  • Fewer support tickets
  • Better user confidence

Risks of ignoring

  • Confusion and churn
  • More manual support work

Expectations

  • Improves: onboarding and clarity
  • Does not guarantee: user satisfaction

How

Step-by-step method

  1. Write a five step quick start for users.
  2. Write a three step local setup for developers.
  3. Add a short troubleshooting section.
  4. Link to the next action.

Do and don't

Do

  • Keep sections short and direct
  • Use plain language and numbered steps

Don't

  • Hide key steps in long paragraphs
  • Assume users know your stack

Common mistakes and fixes

  • Mistake: Docs are too long. Fix: Cut to the shortest useful version.
  • Mistake: No troubleshooting. Fix: Add 3 common issues.

Done when

  • User guide has a clear quick start.
  • Setup doc works on a clean machine.
  • Troubleshooting is included.

Guided exercise (10 to 15 min)

Inputs

  • Your MVP workflow
  • Setup steps

Steps

  1. Write the user quick start.
  2. Write the developer setup.
  3. Add troubleshooting.

Output format

Field Value
Quick start
Setup steps
Troubleshooting
Next action

Pro tip: Write the quick start as if the user has 60 seconds.

Independent exercise (5 to 10 min)

Task

Cut one paragraph and keep the meaning.

Output

Shorter doc.

Self-check (yes/no)

  • Is there a user quick start?
  • Are setup steps clear?
  • Is troubleshooting included?
  • Is the next action obvious?

Baseline metric (recommended)

  • Score: 3 of 4 checks met
  • Date: 2026-02-06
  • Tool used: Notes app

Bibliography (sources used)

  1. Write the Docs Guide. Write the Docs. 2024-01-01. Read: https://www.writethedocs.org/guide/

  2. Readme Best Practices. GitHub. 2024-01-01. Read: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

Read more (optional)

  1. Documentation Guide Why: Examples of effective docs. Read: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/