Before the first game: admin manuals, data and tutorials¶

Exercise admin-manuals-data-tutorials-annex.pdf · PDF

Before anyone plays a new board game, somebody punches out the pieces, sorts the cards and reads how many of each there should be. Is that person a player yet? No. For ten minutes, they are the administrator. And the first game is never a real game: it is the beginners' set-up, on rails.

Three things are left in the box that you have not written: the page for the person who sets it up, the list of components, and the first guided game. In your app, those are the admin manuals, the data structure page and the tutorial. Whoever runs your project in June, including your teacher, will start with these pages.

Three manuals for the one who runs it¶

The reader has changed. It is no longer the user: it is whoever installs the app and keeps it working. In a company, that is the IT department. For your project, it is the teacher who has to run it.

They come to you at three different moments, so there are three manuals:

Once at the start, whenever something must change, and every week after. They can share one page with three sections, as long as they stay separate.

Three rules keep them honest:

• Versions, always. "Install Node" is not an instruction. "Node.js 24 or later; check with node --version" is.
• Commands are copied, not retyped. Every command goes in a code block, alone on its line, exactly as it must be typed.
• An installation ends with a check. The reader must know whether it worked without asking you.

A page in your docs site, usually docs/admin.md, has these sections:

What the app remembers¶

Persistent data is what the app still knows after you close it.

Everything else was in memory and is gone. For a board game, it is the list of components: Catan has 19 terrain hexes and 95 resource cards. If a piece goes missing, that list is how you know.

You can look at your app's memory directly. Open NoteBox in the browser and press F12, then go to Application → Local Storage (in Firefox the panel is called Storage). You see two keys, notebox.notes and notebox.settings. Click the first: it holds a JSON array.

Now add a note with the tags Home, FOOD, home and watch the value change:

"tags": ["home", "food"]

Who decided that? Where is that rule written down? Only in the code. If the code is the only place, the next developer finds out by breaking it. The code says what the app does today. A data page says what is guaranteed.

The data page¶

A data page, usually docs/data.md, has five sections:

The diagram¶

An entity is one kind of thing your app stores. An entity-relationship diagram shows the entities, their fields and how they connect. In Markdown, you write it as a Mermaid erDiagram:

```mermaid
erDiagram
    NOTE {
        string id PK
        string title
        boolean pinned
    }
    TAG {
        string name
    }
    NOTE ||--o{ TAG : "tags (0 to 5)"
```

Zensical draws it like this:

erDiagram
    NOTE {
        string id PK
        string title
        boolean pinned
    }
    TAG {
        string name
    }
    NOTE ||--o{ TAG : "tags (0 to 5)"

PK marks the primary key, the field that identifies each record. The symbols on the line give the cardinality, how many of one thing go with another. ||--o{ reads: one note has zero or more tags.

If the diagram does not render, remember that Mermaid is strict: entity names without spaces, one field per line, type first.

A complete example¶

To see all the sections together, take an imaginary app, ShelfLog, which tracks the books you read and keeps them in localStorage:

Where and how

localStorage, key shelflog.books, a JSON array. Structure version 1.

{
  "id": "7b1e4c90-2f3a-4d11-9a55-08c2f1d3e6aa",
  "title": "Dune",
  "pages": 612,
  "finishedAt": "2027-01-17T20:15:00.000Z"
}

Limits and backup

About 5 MB per site, the usual localStorage limit. Clearing the browser's data deletes it. The backup file holds the whole array.

Three mistakes show up again and again:

• Types copied from the language, not from the data. "Date" is not a type on disk. A date on disk is a string in a format, so write which one: ISO 8601, like 2027-02-09T08:10:42.120Z.
• An empty Rules column. Can it be empty? Can it repeat? What is the maximum? If the app checks it, it is a rule. Try to break your own app and see what happens.
• Invented examples. In your own page, copy a real value from DevTools or from the file.

Tutorial or manual?¶

What is the difference between the rules of Catan and the beginners' set-up? The rules cover every case. The set-up plays one game for you: this exact board, these exact pieces. Nobody learns a game from the rules. They learn it from the first game.

A tutorial teaches by walking a beginner through one guided example, from start to finish.

A manual serves someone who knows what they want. A tutorial serves someone who does not yet know what there is to want. The Diátaxis framework calls tutorials "learning-oriented", and it gives you these rules:

1. Say what they will have at the end, in the first sentence, and how long it takes.
2. Use one concrete example. Tell them exactly what to type ("type Weekend shopping"), not "type a title".
3. End every step with "You should see..." If they cannot see it, they do not know whether to go on.
4. Offer no choices and no explanations. No "you can also...". No "this works because...". Link to the manual instead: explanations in the middle are where learners stop.
5. Make it work every time, from a clean app. Test it from zero before you publish it.

Here is the opening of the NoteBox tutorial:

# Tutorial: your first note

In two minutes you will write a shopping note, tag it, pin it, and delete it
by mistake without losing it.

## 1. Create the note

Type `Weekend shopping` in **New note title** and press **Add**.

You should see the note in the list, and the editor open on the right.

Here is a complete one, for the imaginary ShelfLog. Five steps are enough, because a tutorial that is finished beats one that is complete:

# Tutorial: log your first book

In two minutes you will add a book, mark it as finished and find it again.

## 1. Add the book

Type `Dune` in **Book title**, type `612` in **Pages** and press **Add book**.

You should see Dune at the top of the list, with the label *Reading*.

## 2. Open it

Press **Dune** in the list.

You should see its details on the right, with 612 pages.

## 3. Finish it

Press **Mark as finished**.

You should see the label change from *Reading* to *Finished*.

## 4. Filter the list

Choose **Finished** in **Show**.

You should see a list with only Dune in it.

## 5. Search for it

Type `dun` in **Search**.

You should see Dune stay in the list as you type.

You have now added, finished and found a book. Next, read
[Import a list of books](user-manual.md#import-a-list-of-books).

Four things go wrong most often:

• It is the manual again ("To add a note, press Add"). What exactly do I type?
• "You should see" is missing or vague ("you should see that it works"). What appears, and where?
• Step 3 depends on data the author has and the reader does not. A tutorial starts from the empty app.
• Ten steps. Five.

Then reset your app's data and follow your own tutorial literally, from zero. If you get stuck, so will they.

Rebuild it all from a clean copy¶

You now have every page in the box. One last test: take a clean copy of your project, install it, start the preview in one terminal as your screenshot script expects, and rebuild the lot in another.

npm run docs:shots
zensical build --clean
npm run docs:pdf

If it only works on your PC, your installation manual is wrong.

Key takeaways¶

• Installation gets the app running and ends with a check. Configuration lists every option. Administration keeps it alive with backup, restore, update and reset.
• Always give versions, and put each command alone in a code block.
• Persistent data is what the app still knows after closing, and that includes localStorage, files and cookies.
• A data page says where and how, shows an erDiagram, gives each entity a table (Field · Type · Required · Rules · Example) and a real example.
• A tutorial walks a beginner through one concrete example, with no choices, and every step ends with "You should see...".
• A user manual serves someone who already knows what they want. A tutorial serves someone who is still finding out.

Quick check¶

That completes the box: rules, almanac, text on the cards, set-up sheet, list of components and first game. In Unit 8 you put your app into a box of its own, with a real installer.