User Documentation In deze handleiding leer je hoe je een handleiding kunt maken.
Een handleiding is een les die je door een reeks praktische stappen begeleidt. Het biedt een leerervaring door iets te doen. Het is de beste manier om kennis te maken met een onderwerp waarmee je nog niet bekend bent. Handleidingen zijn cruciaal in elke documentatie: ze laten nieuwkomers rondkijken, ze begeleiden de eerste stappen, ze zijn de etalage, ze geven een fijne en gemakkelijke ervaring van een onderwerp. Een van de "trucs" om dit te bereiken is om alles weg te laten wat kan afleiden tijdens het leerproces. Bijvoorbeeld:
- Alternatieve manieren om iets te doen of manieren om iets heel specifieks te doen.
- Volledige verwijzingen van alle opties en een technische beschrijving van de structuur ervan.
- Gedetailleerde uitleg en historische achtergronden.
Die extra informatie kan het beste apart worden aangeboden. Vermijd zoveel mogelijk om dit erin te verwerken, want dat vertroebelt alleen maar de handleiding. Dit is het hoofdprincipe van het Diátaxis Framework, een systematische manier om documentatie te verbeteren. Plaats de hierboven genoemde extra informatie in bijbehorende how-to gidsen, verwijzingen en uitleg. In de how-to gidsen kun je snel vinden hoe je iets specifieks voor elkaar krijgt. In verwijzingen kun je opzoeken hoe dingen werken, welke opties ze hebben en waar je meer informatie kunt vinden. Met uitleg kun je je begrip van het onderwerp verdiepen.
Hoewel een handleiding een introductie tot een onderwerp biedt, is het niet uitsluitend gericht op beginners. Het kan ook een introductie tot een gevorderd onderwerp zijn! Maak aan het begin van je handleiding duidelijk welke kennis of vaardigheid nodig is om de handleiding te kunnen volgen.
Als je iemand leert koken, moet je dingen uitleggen zoals snijtechnieken, hoe een oven te gebruiken en andere basiszaken in de keuken. Je begint met een eenvoudig recept, bij voorkeur iets dat gemakkelijk een mooi eindresultaat oplevert. Dat eindresultaat zelf is niet het hoofddoel: je wilt bepaalde vaardigheden aanleren. Dit is wat een handleiding doet. Iemand die al kan koken en iets specifieks wil maken, heeft zo'n handleiding niet nodig, maar een recept. Recepten zijn de how-to gidsen van koken.
Stap voor stap
Om een handleiding te maken:
- Verzamel informatie over het onderwerp. Bestaande documentatie, video's, enz. Noteer dingen die verwarrend waren of waar je tijd nodig had om ze te begrijpen. Zijn er vragen over het onderwerp op het forum?
- Welke concepten zijn erbij betrokken? Een klein diagram schetsen kan helpen. Probeer niet volledig te zijn, maar maak duidelijk wat belangrijk is voor deze handleiding en wat niet.
- Is er specifieke kennis of een vaardigheid nodig om aan te leren in je handleiding?
- Maak een voorbeeld waarin je alle concepten en vaardigheden kunt gebruiken die je in de handleiding wilt overbrengen. Maak het voorbeeld zo eenvoudig mogelijk.
- Bepaal en schrijf stappen om tot een eindresultaat te komen. Elke stap moet door je student herhaalbaar zijn.
- Filter alle uitleg, verwijzingen, alternatieven en speciale gevallen eruit; zet ze in aparte artikelen.
- Schrijf een inleiding. Wat ga je leren in deze handleiding? Vermeld eventuele vereisten die nodig zijn om de handleiding te doen.
- Schrijf de samenvatting. Wat hebben we geleerd? Je kunt ook vermelden welke volgende stappen te nemen zijn om meer te leren.
- Voeg schermafbeeldingen met annotaties toe om de te nemen acties te illustreren. Tip: gebruik nummers in de schermafbeelding en geef uitleg in de tekst. Dat maakt het makkelijker om je schermafbeelding opnieuw te gebruiken in vertalingen en minimaliseert de inspanning om taalspecifieke schermafbeeldingen te maken.
- Voeg diagrammen toe om structuren, relaties en processen uit te leggen.
- Voeg de bijbehorende artikelen toe met uitleg, verwijzingen en how-to gidsen.
- Plaats alle artikelen van één onderwerp onder een overzichtsartikel, waarin uitgelegd wordt wat wat is, hoe ze zich tot elkaar verhouden en waar te beginnen.
Voorbeeld: Een artikel maken en publiceren in Joomla
Laten we als voorbeeld een handleiding maken over hoe je een artikel maakt en publiceert onder een menu-item in Joomla.
Informatie verzamelen
In onze gebruikershandleiding vind je relevante artikelen onder "Aan de slag", "Artikelen" en "Menu's". Het is vaak verwarrend wanneer je met Joomla begint, dat je een artikel niet ziet nadat je het hebt gemaakt, ook al heb je het gemarkeerd als "gepubliceerd". Om het artikel te zien, moet er een link naartoe zijn. Er zijn verschillende manieren om zo'n link te maken (zoals een menu-item of een categorie blogweergave of door het op de startpagina blogweergave te zetten door het artikel als speciaal te markeren of te linken vanuit een ander artikel), maar we gaan ons nu richten op het beschikbaar maken van het artikel via een menu-item.
Concepten & Vaardigheden
We hebben 'inhoud', 'artikel', 'menu' en 'menu-item'. We moeten deze termen verduidelijken. We laten zien waar je deze dingen vindt in het beheermenu. We laten 'categorieën' of 'speciaal' buiten beschouwing in deze handleiding.
Vereisten
U moet toegang hebben tot de beheerderskant van een werkende Joomla-website en weten hoe u moet inloggen.
Doel
Ons doel is om te leren hoe we een nieuw Joomla-artikel en een nieuw menu-item kunnen maken waaronder we ons artikel plaatsen.
Stappen
Gebruik de volgende stappen om ons doel te bereiken:
A. Maak een artikel
- Log in op uw Joomla beheerderspaneel.
- Eerst gaan we het artikel maken. Navigeer naar het menu "Inhoud" aan de linkerkant en selecteer "Artikelen".
- Klik op "Nieuw" om een nieuw artikel te maken.
- Vul een titel en inhoud in voor uw artikel.
- Klik op "Opslaan en Sluiten" om uw artikel op te slaan.
B. Maak een menu-item dat naar het artikel verwijst
om het artikel op de website te tonen gaan we een menu-item maken dat naar het artikel verwijst. Navigeer naar het menu "Menu's" aan de linkerkant en selecteer "Hoofdmenu".
- Net als bij een artikel, klik op "Nieuw" om een nieuw menu-item te maken.
- Vul een titel in voor uw menu-item. Dit is de titel zoals die in het menu zal verschijnen. Deze hoeft niet hetzelfde te zijn als de titel van het artikel. Meestal is deze korter dan de titel van een artikel zodat het beter in het menu past.
- Selecteer een menu-itemtype: onder "Artikelen" selecteert u "Enkel artikel".
- Selecteer het artikel: selecteer het artikel dat we zojuist hebben gemaakt.
- Ga naar de website en vernieuw de pagina. Gefeliciteerd: u kunt nu op het menu-item klikken om uw artikel te zien.
Inleiding
Schrijf de inleiding: wat gaat u leren in deze handleiding en welke vereisten zijn nodig.
Filter aanvullende informatie eruit
Kunnen we iets weglaten van wat tot nu toe geschreven is? In stap 2 van het maken van een menu-item noemde ik dat de titel van het menu-item niet hetzelfde hoeft te zijn als de titel van het artikel. Is dat een noodzakelijke toevoeging aan deze handleiding? Zo niet, dan kunnen we het beter voorlopig weglaten. Maar het geeft een aanwijzing voor een meer gespecialiseerd artikel over artikeltitels en menutitels en wanneer deze worden weergegeven, waarbij de algemene artikelopties, de individuele artikelinstellingen onder het tabblad opties, de menu-iteminstellingen onder het tabblad opties van het menu-item en meer betrokken zijn. Het zou ook goed zijn om een verwijzing-type artikel te maken over hoe artikelen, categorieën en menu-items samenwerken; probeer in zo'n artikel volledig te zijn en alle mogelijkheden op te sommen. Een gespecialiseerd how-to artikel zou kunnen zijn: "Hoe de artikeltitel weer te geven?", waarin de instellingen in de algemene artikelinstellingen, en in de individuele artikel- en menu-iteminstellingen worden getoond. Een uitleg-type artikel zou iets kunnen vertellen over de achtergrond waarom Joomla "artikel" gebruikt waar bijvoorbeeld WordPress "bericht" gebruikt, of hoe het artikel wordt weergegeven op de uiteindelijke pagina.
Conclusie
Vat alles samen in een overzicht. En vermeld enkele mogelijke volgende stappen om meer te leren (zoals: een handleiding over het toevoegen van een categorie of een how-to gids over de opslaan-naar-menu snelkoppeling).
Afbeeldingen en grafieken
Maak schermafbeeldingen die de knoppen en velden tonen die betrokken zijn bij het maken van een artikel en een menu-item. Markeer de betrokken knoppen en velden.
Voor de duidelijkheid kunt u een diagram toevoegen dat laat zien hoe een artikel "onder" een menu-item wordt geplaatst.
Verwijzingen, how-to gidsen en uitleg toevoegen
Plaats alle aanvullende informatie en instructies in aparte artikelen.
Overzicht
Als u meerdere artikelen over één onderwerp heeft, moet u een overzichtsartikel maken, waarin wordt uitgelegd hoe de artikelen met elkaar samenhangen en waar u moet beginnen.
Oefening
Begin met het maken van de bovenstaande handleiding over hoe u een artikel in Joomla maakt en publiceert. De beste manier om te leren is door het te doen. We zullen een voorbeeld publiceren van hoe dit eruit kan zien in de huidige gebruikershandleiding op deze website. Maar we plaatsen graag uw versie als u de huidige kunt verbeteren.
(dit artikel is ook gepubliceerd in het Joomla Community Magazine van februari 2025)