Handleiding schrijven

Dit deel is voor wie de handleiding schrijft. Het laat zien hoe de site in elkaar zit en welke bouwstenen je kunt gebruiken. Elke bouwsteen staat erbij met de Markdown die hem maakt, zodat je hem kunt overnemen.

Onderwerp	Wat je leert
Menu en submenu's	Hoe het menu bovenaan en links ontstaat, en hoe je een pagina toevoegt
Afbeeldingen	Schermafbeeldingen plaatsen: grootte, uitlijning, onderschrift, licht en donker
Opmaak en bouwstenen	Meldingen, tabbladen, tabellen, knoppen, iconen, toetsen en meer
Diagrammen	Stroomschema's en volgordediagrammen, getekend met tekst

Waar alles staat

De handleiding is het project src/EventOps.Help in de EventOps-repository:

src/EventOps.Help/
├── mkdocs.yml               # instellingen van de site, en het menu (nav)
├── requirements.txt         # welke versie van MkDocs Material we gebruiken
├── includes/
│   └── afkortingen.md       # afkortingen, toegevoegd aan elke pagina
└── docs/                    # de pagina's
    ├── index.md             # de startpagina
    ├── afbeeldingen/        # logo en favicon
    ├── stylesheets/         # de EventOps-kleuren
    ├── javascripts/         # Mermaid, voor de diagrammen
    ├── aan-de-slag/
    │   ├── index.md         # de pagina achter "Aan de slag" zelf
    │   ├── inloggen.md
    │   └── afbeeldingen/    # de schermafbeeldingen van dit deel
    ├── deelnemers/
    ├── beheer/
    └── handleiding-schrijven/

Elke map in docs/ is een deel van de handleiding, met zijn eigen afbeeldingen/-map ernaast.

Lokaal bekijken

Je hoeft niet te wachten op een uitrol om je pagina te zien. Eén keer installeren:

cd src/EventOps.Help
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Daarna, elke keer dat je schrijft:

cd src/EventOps.Help
source .venv/bin/activate
mkdocs serve

Open http://127.0.0.1:8000. Elke keer dat je een bestand opslaat, ververst de pagina vanzelf.

De map .venv

In de map .venv staat de Python-omgeving voor het bekijken. Hij is alleen van jou; Git negeert hem.

Een pagina toevoegen, in drie stappen

1. Maak het bestand aan, bijvoorbeeld docs/beheer/vouchers.md, en begin met een kop: # Vouchers.
2. Zet de pagina in het menu, in mkdocs.yml onder nav: (zie Menu en submenu's).
3. Bekijk het resultaat met mkdocs serve.

Streng bouwen

Bij de uitrol bouwt de pipeline de site met mkdocs build --strict. Strict betekent: bij een fout stopt de bouw, in plaats van een kapotte pagina te publiceren. Fouten zijn bijvoorbeeld:

• een link naar een pagina die niet bestaat, of naar een kop die er niet (meer) is;
• een afbeelding die niet op de genoemde plek staat;
• een pagina die wel geschreven is, maar niet in het menu staat.

Doe dezelfde controle zelf voordat je iets instuurt:

mkdocs build --strict

Staat er aan het eind geen WARNING of ERROR, dan is het goed.

Zo schrijven we

• Je, niet u: we spreken de lezer aan met je.
• Knoppen en menu-items vet, precies zoals ze in EventOps heten: klik op Afrekenen.
• Menupaden met een pijl: Tenant · Beheer → Gebruikers.
• Korte stappen, genummerd, één handeling per stap.
• Fictieve gegevens in voorbeelden en schermafbeeldingen: namen als Fictief Opleidingen B.V. en e-mailadressen op @anonymous.invalid. Nooit echte klanten of deelnemers.

Uitrollen

Staat je wijziging op main, dan bouwt de pipeline een nieuwe versie van de site en komt die bij de volgende release online, op https://help.eventops.qtopia.nl.