User Documentation

Salary

This task pays a fixed salary of 12 MVP points, plus up to 18 quality points for exceeding the minimum requirements — for a total of 30 points, with a maximum of 5 points per person.

Background

This section guide you to some additional material that will help you understand the task better. It is not mandatory to read it, but it can be useful for your team.

• Using the Diátaxis Framework to Write Your Project Documentation

Minimum Viable Product (MVP)

Create clear user-facing documentation that introduces the system and shows how to use every feature and why it’s useful. Write a short elevator pitch (3–5 sentences) and, for each feature, include a brief description and a step-by-step usage guide with expected input/output. Keep the language beginner-friendly so a new user can follow it without prior knowledge of your project.

All files must live under docs/user/ at the repository root (Markdown or simple HTML). Provide an entry page docs/user/index.md that links to each feature page. From your project README.md, add a visible “User Guide” link to docs/user/index.md. Do not include code tours—focus on what the user does and sees.

Example: Team 'ByteBusters' ship a simple guide

docs/user/index.md has: Overview (pitch), Quick Start (how to run), and links to Add, List, Search, Save, Load. Each feature page shows a short terminal transcript and a tiny flow diagram. Screenshots use a large font so they’re readable.

Technical Details

Author your user docs as plain HTML or MD files so any IDE (VS Code, IntelliJ, PyCharm, etc.) can edit and preview them easily. Keep all documentation under docs/user/, use relative links only (so everything works when viewed on others computer), and open files directly in a browser to check layout and navigation. Recommended folder structure:

docs/
  user/
    index.html
    quick-start.html
    features/
      add-book.html
      list-books.html
      search.html
      save.html
      load.html
    assets/
      css/
      img/

Editing tips: use simple, readable headings (<h1>…</h1>, <h2>…</h2>), lists for steps, and screenshots in assets/img/ with meaningful alt text; avoid spaces in filenames and keep paths lowercase. After each edit, proofread: run your IDE’s spellchecker, click every link to catch 404s, view pages at 125–150% zoom to ensure readable font size, and do a buddy read-through (teammate follows the steps exactly on their machine). Before submission, verify that README.md links to docs/user/index.html, and that the whole docs folder renders correctly when browsed.

Quality

High-quality docs are pleasant, consistent, and efficient to read. Use clear headings, bullets, and consistent formatting; include a small Glossary for any terms (e.g., “record,” “pattern,” “CSV”). Make sure a new user can run the app by following only index.md → quick-start.md; if extra knowledge is needed, point to where to get it (e.g., “See official Python/Java install instructions”). Add a tiny Troubleshooting section with 2–3 common problems and fixes.

Aim for readability: large terminal font in screenshots, short paragraphs, and one task per page. Keep examples real and test them—copy the commands from your docs and run them to ensure they work. A tidy, friendly user guide shows respect for users and reduces tutor questions during demos.

Example: Team 'NullPointers' write for humans

Their quick-start.md has copy-paste commands for Windows/Mac/Linux, plus a “If you see ‘command not found’…” tip. Each feature page ends with a tiny FAQ. The docs read smoothly and a new user can use the tool in minutes.

Example: Team 'PixelPenguins' visualize behavior

For the cellular automaton, they add a one-image legend (alive/dead cell) and a 20-second clip showing Toggle cell → Step. The glossary explains “generation” and “neighborhood” in one sentence each, keeping the guide friendly to non-experts.