Documentatie toevoegen

Het komt wel eens voor dat je zélf een stukje uitleg heb gemaakt over een OpenAC feature. Bijvoorbeeld om aan je gebruikers uit te leggen wat de OpenAC release notes precies betekenen of wat er voor ze verandert. Zo'n stukje uitleg is vaak niet alleen voor jezelf en je eigen organisatie nuttig, maar voor iedereen.

Hoe krijg je dat in de officiële OpenAC documentatie?

Het komt wel eens voor dat je in de gebruikershandleiding zoekt en iets níet vindt. Het is een nieuwe feature, of het ene gebruiksgeval waar je aan denkt wordt niet behandeld. Maar gelukkig weet je wel zelf hoe het werkt, en kan je dat omschrijven. Daarmee zou je de handleidingen kunnen uitbreiden.

Hoe krijg je dat in de officiële OpenAC documentatie?

Procedures

De OpenAC documentatie is geschreven in een wiki. Er zijn twee manieren om iets aan de wiki toe te voegen:

• Rechtstreeks wijzigen: de wiki-pagina's editen en gelijk wegschrijven. Hiermee wijzig je meteen de documentatie die voor iedereen zichtbaar is. Omdat dit nogal grote effecten kan hebben, laten we dit meestal alleen toe aan onze documentatie-schrijver en de FENAC ontwikkelaars. Het is wel mogelijk om beperkte rechten voor rechtstreeks wijzigen te krijgen: als je heel graag een bepaald deel van de documentatie aan zou willen pakken, is het mogelijk om toegang te krijgen tot een enkele pagina of een gebied.
• Ticket maken: je kan ook een ticket maken en in de description of in de comments van dat ticket, de documentatie schrijven. Daarna is het voor ons eenvoudig om die tekst over te nemen naar de wiki, omdat de layout die voor tickets gebruikt wordt dezelfde is als voor de documentatie zelf.

Onze voorkeur gaat uit naar de tweede keus, tickets maken. Daar is ook iets meer geschiedenis zichtbaar.

Layout

Tickets en de wiki gebruiken hetzelfde layout taaltje. De volledige uitleg vind je (in het Engels) in de wiki zelf. Hier volgt een hele korte samenvatting:

• Kopjes doe je met een of meer =-tekens rondom de kop. Méér =-tekens betekent een kleinere kop. De meeste pagina's in de wiki beginnen met twee. Het kopje "Layout", hier, is een sub-kopje binnen de pagina, en krijgt drie tekens, zo: === Layout ===. Als er nog sub-sub-kopjes zouden zijn, dan kregen die vier =-tekens.
• Schuin gedrukt doe je met twee '-tekens aan elke kant van de tekst, zo: ''Schuin''.
• Vet maak je met drie '-tekens aan elke kant, zo: '''Vet'''.
• Onderstreept maak je met twee _-tekens (underscore), zo: __Onderstreept__.

Onderstrepen wordt gebruikt om verwijzingen naar de OpenAC user-interface te maken. Bijv: "Klik op 1. Dossier in het hoofdscherm op het dossierscherm te openen." Om woorden te benadrukken wordt déze manier toegepast. Al zijn er echter nog wel plekken waar dat met vet of cursief gedaan is, dat zal op termijn verdwijnen.

Plaatjes

Om een plaatje op te nemen in tekst, moet je eerst het plaatje aanhangen aan de pagina of ticket die je aan het bewerken bent. Dat doe je met de attach-knop (of bestand toevoegen).

Als het bestand (plaatje) aan de pagina is gehangen, kan je met [[Image(bestandsnaam)]] het plaatje in de tekst opnemen. Zie de macro-documentatie voor meer gegevens. De OpenAC versie ondersteunt ook nog een extra optie class= waarmee je de positie van het plaatje kunt beïnvloeden.

Voorbeelden

Elke pagina, ook als je niet ingelogd bent, heeft onderaan een linkje in andere indeling downloaden. Daar staat altijd Platte tekst bij. Klik daarop om de bron-tekst van de pagina te krijgen (bijvoorbeeld van deze pagina). Dat is een goeie bron van voorbeelden, en ook een manier om een bestaande pagina te kopiëren om te wijzigen.

Experimenteren

Elk AC heeft een implementatieblad dat onder eigen beheer valt. Daar kan je experimenteren of desnoods een stuk documentatie schrijven om later elders in de wiki te plakken (maar eigenlijk is het dan makkelijker om een ticket te maken).

Inhoudelijke Procedures

De documentatie van OpenAC proberen we toegankelijk voor alle AC's te houden. Dat betekent dat je op een paar dingen moet letten bij het schrijven van de documentatie:

• Houd het bij algemene procedures. De specifieke werkwijze van één AC, proberen we niet in de documentatie te beschrijven -- behalve als voorbeeld, of als er binnen het werkverband een consensus is ontstaan dat dat een breed-gedragen wenselijke werkwijze is.
• Let op patiëntgegevens als je screenshots maakt. We proberen zo veel mogelijk met test- of anonieme gegevens de documentatie te maken, zodat er geen echte casussen of NAW gegevens in de tekst terecht komen.

Structuur

Elke pagina begint met deze indeling (dit is een voorbeeld van deze pagina zelf):

[[TOC(heading=Documentatie toevoegen)]]
[[TOC(heading=HOWTO's, sectionindex, compact, depth=3, allactive, Documentatie/Beheerder/HowTos/)]]
[[TOC(heading=Beheerder, sectionindex, compact, depth=2, allactive, indirect=Documentatie/Beheerder/TOC)]]
[[TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)]]

= Documentatie toevoegen =

Dat geeft rechtsboven op de pagina de inhoudsopgave weer in het geel. Hoe dieper de documentatie in de structuur, hoe meer lagen. Bovenstaand voorbeeld heeft er 4. Allemaal met hun eigen depth aangegeven. De bovenste regel laat alle koppen van de pagina zelf weergeven. En regel 3 is een bijzondere regel:

[[TOC(heading=Beheerder, sectionindex, compact, depth=2, allactive, indirect=Documentatie/Beheerder/TOC)]]

Normaliter worden alle pagina's in map in het bovenste voorbeeld HowTo's alfabetisch in de inhoudsopgave weergegeven. Maar je kunt ook gebruik maken van een TOC bestand, (deze komt uit het voorbeeld: Documentatie/Beheerder/TOC) daar kan de volgorde in aangepast worden. Zoals te zien is moet er ook een indirect= vermelding voor. Een TOC bestand zelf mag geen extra spaties of enters bevatten, anders functioneert hij niet.

Hier een ander voorbeeld, deze is wel 5 lagen diep:

[[TOC(heading=FENAC-Indicatoren)]]
[[TOC(heading=Kwaliteit, sectionindex, compact, depth=4, allactive, Documentatie/Manager/Rapportages/Kwaliteit/)]]
[[TOC(heading=Rapportages, sectionindex, compact, depth=3, allactive, Documentatie/Manager/Rapportages/)]] 
[[TOC(heading=Manager, sectionindex, compact, depth=2, allactive, Documentatie/Manager/)]]
[[TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)]]

= FENAC-Indicatoren =

In dit voorbeeld wordt geen gebruik gemaakt van een TOC bestand. Hier blijkt een alfabetische inhoudsopgave elke keer te volstaan.