Inleiding

Er zijn verschillende manieren om aan informatie te komen :

  1. (chrono)logisch, zoals bladzijde voor bladzijde, regel voor regel lezen, tot je het einde van de publicatie bereikt,
  2. thematisch, zoals naar de inhoudsopgave gaan en meteen naar het deel springen waarin je geïnteresseerd bent, op voorwaarde dat de inhoud is opgedeeld in betekenisvolle inhoudseenheden,
  3. transversaal, zoals een sectie „gerelateerde berichten" volgen op basis van inhoudelijke gelijkenis (handmatig gedefinieerd, met tags & trefwoorden, of aangeleerd door AI-onderwerpanalyse), of expliciete kruisverwijzingen. De meeste websites hebben bijvoorbeeld archieven die alle pagina’s met een bepaalde tag/trefwoord opsommen, boeken hebben verklarende woordenlijsten.
  4. hintgebaseerd, zoals het presenteren van een bibliografie met diepgaandere publicaties of een sectie „meer info" aan het einde van de inhoud, of vooruitlopen op latere inhoud,
  5. brongebaseerd, waarbij je verwijzingen (meestal voetnoten of kanttekeningen) volgt naar publicaties waaruit de informatie is gehaald, voornamelijk voor verificatiedoeleinden,
  6. informatie-ophaling, oftewel een zoekmachine.

Je moet ze allemaal tegelijk ondersteunen, want ze zijn complementair en welke in een gegeven context het beste is, hangt af van de voorkennis en behoeften van de lezer. Geen van deze manieren is superieur aan de andere. Dit betekent dat er een flinke dosis „trefwoorden proppen" in je schrijfwerk zit, om te verzekeren dat trefwoordgebaseerde inhoudsanalyse en informatie-ophaling via trefwoorden werken zoals verwacht.

Een handleiding/documentatie is geen cursus, maar vasthouden aan een droge lijst van functies/GUI-bedieningen en hun definitie is… te droog. Je moet verbanden tussen inhoud creëren (wat niet louter HTML-links zijn). In Ansel beginnen workflows met een doel en ontvouwen ze het gereedschap om dit te bereiken. Documentatie begint met het gereedschap en presenteert hoe en waar het gebruikt kan worden. Maar dat zijn de twee uiteinden van het spectrum, en de werkelijkheid zit altijd een beetje ertussenin.

Kennis is sowieso een netwerkgraaf . Je moet alleen op de verbindingen tussen de knooppunten letten. Ze zijn minstens zo belangrijk als de inhoud.

Praktische implementatie in Ansel

Ansel gebruikt Hugo  als CMS, zowel voor de documentatie als voor de rest van de website. De praktische implementatie van de hierboven verwoorde principes zal moeten omgaan met Hugo’s kernfuncties.

(Chrono)logische en thematische toegang

Hugo-inhoud is georganiseerd in secties  die in wezen submappen zijn van de hoofdmap /content. Submappen kunnen oneindig genest worden. Het thema van de website toont de boomstructuur van alle secties in de linkerzijbalk, op brede schermen (desktop). De bovenste niveaus van secties en subsecties kunnen op verzoek van de gebruiker in- of uitgeklapt worden. Deze boomstructuur biedt de inhoudsopgave op het hoogste niveau, die als thematische toegang fungeert.

Binnen secties kan de relatieve volgorde van pagina’s handmatig gedefinieerd worden met de weight-parameter  in Markdown-headers, zoals dit :

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

De weight-parameter is optioneel. Als hij niet gebruikt wordt, gebruiken de paginalijsten meestal de date om inhoud te ordenen, maar ze zouden ook alfabetische ordening op paginatitel kunnen gebruiken. Deze ordening biedt de (chrono)logische toegang.

Binnen pagina’s, als er meer dan twee secties in de inhoud zijn (gedefinieerd door tweedeniveautitels, bijv. <h2> in HTML of ## in Markdown), voegt Hugo automatisch een interne inhoudsopgave toe in de rechterzijbalk, op brede schermen (desktop).

Transversale toegang

Tags kunnen op de website gedefinieerd worden met de tags-parameter in de Markdown-header, zoals dit :

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

Tags zijn optioneel en worden op verschillende plaatsen in het websitethema als klikbare links weergegeven. Op een tag klikken opent het archief ervan, met een lijst van alle pagina’s die deze tag hebben. Dit biedt transversale toegang.

Schrijvers worden ook aangemoedigd om kruislinks in hun inhoud toe te voegen, van websitepagina’s naar andere websitepagina’s, om transversale toegang te bevorderen. Concepten die een vermelding op de website hebben, moeten omgezet worden in links naar de pagina die elk concept beschrijft.

Hintgebaseerd

Schrijvers zijn vrij om een sectie Bibliografie of Meer informatie aan het einde van hun pagina’s toe te voegen, met een lijst van publicaties en links. Die publicaties kunnen intern of extern aan het Ansel-project zijn. Ze kunnen zijdelings verband houden met het onderwerp dat in de inhoud behandeld wordt.

Het is ook mogelijk om pagina’s af te sluiten met een opening naar de volgende logische stap, wanneer je over workflows of modules schrijft.

Brongebaseerd

Hugo ondersteunt uitgebreide Markdown, die voetnoten ondersteunt . Deze worden aanbevolen om bronnen te vermelden, zoals dit :

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

Ansel heeft op dit moment nog niet gekozen voor een specifieke academische opmaak van bronvermeldingen, hoewel de IEEE-citatiestijl  het best geschikt lijkt voor de voetnootbenadering met numerieke index.

Zorg ervoor dat je de DOI  van de publicatie opneemt, of op zijn minst een langetermijn-URL waarop hij nu en in de toekomst opgehaald kan worden.

Informatie-ophaling

Voorlopig handelt Chantal  dat deel af. De webindex wordt handmatig en periodiek bijgewerkt.

Richtlijnen

Schrijven, zelfs technisch schrijven, is een kunst die moeilijk te reduceren is tot een reeks vaste richtlijnen of best practices, omdat dit varieert naargelang de context. Je moet oppassen dat je niet roomser wordt dan de paus. Een goede vuistregel is om te schrijven om problemen op te lossen, wat betekent dat je begint met jezelf af te vragen waarom en vanwaar de lezer op de pagina die je schrijft terecht is gekomen :

  1. wat voor kennis wordt van de lezer verondersteld/aangenomen dat hij al heeft ?
    • de lezer zou zich idealiter bewust moeten zijn van die vereisten, dus begin misschien met een lijst van links,
    • alles wat niet in deze lijst staat, moet op je pagina gedefinieerd en uitgelegd worden,
  2. wat voor taak probeert de lezer te voltooien die hem naar deze pagina heeft geleid ?
    • willen ze een snelle spiekbriefje, of een gedetailleerde how-to, of een theoretische achtergrond ? Misschien moet je er willekeurig een kiezen.
    • dit bepaalt welke hints je in de tekst kunt toevoegen om het kennisnetwerk te verbeteren,
    • dit zou waarschijnlijk het hele gezichtspunt van je inhoud en de lengte/diepte ervan moeten kleuren.

Een goede manier om de kwaliteit van documentatie te beoordelen is door te kijken naar de veelgestelde vragen (of minst begrepen onderwerpen) op forums. Als het onderwerp al behandeld is maar er blijven vragen opduiken, kan dat komen doordat de documentatie niet duidelijk is of de relevante pagina’s diep in het netwerk begraven en niet vindbaar genoeg zijn.

Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.