Documentatie schrijven

Het schrijven in markdown vind je in markdown (opens in a new tab)
Het instellen van de gebruikers en rechten vin je in github (opens in a new tab)

Github -> docs.digitalartlab.nl

Op de server staat een script die automatisch de github directory van dal-documentation scant voor wijzigingen. Dit geld voor nieuwe folders en files, en voor wijzigingen in de aanwezige files.
Je gebruikt Visual Studio Code (zie github (opens in a new tab)) om een folder of file toe te voegen. Bij een file gebruik je .mdx als extentie!

In de meeste folders staat een _meta.json file. Daarin kan je aangeven wat je voorkeuren zijn voor de volgorde en benaming van de files in die folder.
Zoals bijvoorbeeld voor de listing van Meta, die vastgelegd staat in de _meta.json in de folder metafolder.

{
  "documentatie_schrijven": "Documentatie Schrijven",
  "markdown": "Schrijven in markdown",
  "github": "Github Gebruikers en Rechten",
  "files": "Files (oud)"
}

Per regel zie je eerst de filenaam zonder de extensie (!). En vervolgens de titel zoals je wilt dat die in de menulijst komt. Vergeet niet een comma achter elke regel te plaatsen, behalve de laatste.
Vaak is alleen stappenplan opgenomen in de meta-file. De andere files komen dan ná stappenplan.

Je ziet vaak alleen één regel, voor stappenplan.mdx. Dat is omdat deze boevenaan moet komen. Als je de volgorde van de andere files ook wilt bepalen moet je die dus opnemen in de meta-file!

Folder Structuur

De folderstructuur is erg belangrijk.

Als je ingelogd bent met github (opens in a new tab) vind je de folder pages en public. In pages vind je de directories en pagina's die automatisch uitgelezen worden. En in pages staan fotos en andere documenten die je wilt embedden in de pagina's. De folder components is voor plugins vooronder andere de callout-tags.

Ook de hoofd directory van pages heeft eem _meta.json file. Het is de bedoeling als je een directory aanmaakt voor een nieuwe toevoeging aan de handleidingen, je deze in Visual Studio Code ook toevoegd aan de main _meta.json-file!

{
  "index": "Introductie",
  "website": {
    "href": "https://digitalartlab.nl",
    "title": "digitalartlab.nl ↗",
    "type": "page"
  },
  "-- Technieken --": {
    "type": "separator",
    "title": "Technieken"
  },
  "3d-printen": "3D printen",
  "3d-scanner": "3D scanner",
  "cnc-frezen": "CNC frezen",
  "hot-press": "Hot press",
  "lasersnijden": "Lasersnijden",
  "vinyl-snijden": "Vinyl snijden",
  "vr-bril": "VR-bril",
  "-- Meta --": {
    "type": "separator"
  },
  "metafolder": "Meta"
}

De source downloaden met Github

Je kunt de documenten online in de github web-omgeving editten, maar door de Github-app te gebruiken voorkom je dat je per wijzigingen eerst verificatie moet vragen aan een andere gebruiker met de juiste rechten.

Download Github (opens in a new tab) en installeer de app op je Mac of PC en login met je Github account.

Selecteer digitalartlab/dal-documentation en klik vervolgens op clone digitalartlab/dal-documentation.
De repro wordt nu naar jouw computer gekopieerd.

⚠️

Let er op dat als je even niet geëdit hebt, dat je eerst in de Github app de laatste versie van de documentatie binnenhaalt! Dat doe je door bovenaan op Fetch te klikken, en daarna op Pull.

Document editten in Visual Studio Code

Voor het editten van de files open je Visual Studio Code en kies je de directory, meestal Documents/Github/dal-documentation.

Vervolgens ga je de documenten editten. Als je een nieuw document wilt toevoegen, geef deze dan de extensie .mdx.

Vergeet niet de _meta.json aan te passen of toe te voegen als dat nodig is.

Plaatjes toevoegen

Plaatjes zoals screendumps zijn nu heel eenvoudig toe te voegen aan de repro. Bewerk ze eerst in Photshop. Houd daarbij een maximale breedte van 1200-1600 pixels aan, en bewaar het in kwaliteit 70-80.
Als je tevreden bent kopieer je ze in de Finder of Verkenner naar de public/assets directory.
Hoe je ze in de tekst embed staat uitgelegd in de markdown (opens in a new tab) handleiding.

Wijzigingen doorvoeren

Sla regelmatig op en ga dan steeds naar de Github app. Je ziet een reeks wijzgingen die je uitgevoerd hebt. Kies Commit en daarna Push Origin. Als je meerdere documenten wijzigt moet je een omschrijving meegeven in de velden boven Commit. Het script op de server haalt eens in de paar minuut de data op van Github. Kijk daarom na ongeveer na een minuut of de wijzigingen doorkomen op docs.digitalartlab.nl (opens in a new tab).

Het is beter im steeds kleine stukjes tekst te editten, zodat je het op tijd doorhebt als er iets misgaat in je syntax. Maar ook omdat iemand anders simultaan bezig kan zijn aan het document..

⚠️

Als na vijf minuten jouw wijzigingen nog niet terug ziet is er waarschijnlijk iets mis in je syntax. Zo vergeet ik bij een <Callback> soms de backslash in de afsluitende <\Callback>.

Stappenplan Schrijven in markdown