Hoe maak je een Joomla Handleiding?
In deze handleiding leer je hoe je een handleiding maakt.
Een handleiding is een les die je stap voor stap begeleidt door een reeks praktische stappen. Het biedt een leerervaring door iets te doen. Het is de beste manier om een onderwerp te leren kennen waar je nog niet mee vertrouwd bent.
Handleidingen zijn cruciaal in elke documentatie: ze helpen nieuwkomers wegwijs te worden, ze begeleiden de eerste stappen, ze zijn de etalage, ze bieden een prettige en gemakkelijke ervaring van een onderwerp. Een van de "trucs" om dit te bereiken is om alles weg te laten dat kan afleiden van het leerproces. Bijvoorbeeld:
- Alternatieve manieren om iets te doen of manieren om iets heel specifieks te doen.
- Volledige referenties van alle opties en een technische beschrijving van de structuur.
- Gedetailleerde uitleg en historische achtergronden.
Die extra informatie kan het beste apart worden verstrekt. Vermijd zoveel mogelijk het mengen ervan, omdat dit alleen maar de handleiding vertroebelt. Dit is het belangrijkste principe van het Diátaxis Framework, een systematische manier om documentatie te verbeteren. Zet de hierboven genoemde extra informatie in respectievelijk handleidingen, referenties en verklaringen. In de handleidingen kun je snel vinden hoe je iets specifieks doet. In de referenties kun je opzoeken hoe dingen werken, welke opties ze hebben en waar je meer informatie kunt vinden. Met verklaringen kun je je begrip van het onderwerp verdiepen.
Hoewel een handleiding een inleiding biedt tot een onderwerp, is het niet uitsluitend gericht op beginners. Het kan ook een inleiding zijn tot een geavanceerd onderwerp! Wees aan het begin van je handleiding duidelijk over welke kennis of vaardigheden nodig zijn om de handleiding te kunnen volgen.
Als je iemand leert koken, moet je dingen uitleggen zoals snijtechnieken, hoe je een oven gebruikt en andere basiskeukenzaken. Je begint met een eenvoudig recept, bij voorkeur iets dat makkelijk een mooi eindproduct oplevert. Het eindproduct zelf is niet het belangrijkste doel: je wilt vaardigheden aanleren. Dit is wat een handleiding doet. Iemand die weet hoe te koken en iets specifieks wil maken, heeft zo’n handleiding niet nodig, maar een recept. Recepten zijn de handleidingen van het koken.
Stap-voor-stap
Om een handleiding te maken:
- Verzamel informatie over het onderwerp. Bestaande documentatie, video's, etc. Noteer dingen die verwarrend zijn of die tijd kostten om te begrijpen. Zijn er vragen over het onderwerp op het forum?
- Welke concepten zijn betrokken? Het tekenen van een klein diagram kan helpen. Probeer niet volledig te zijn, maar maak duidelijk wat belangrijk is voor deze handleiding en wat niet.
- Is er specifieke kennis of vaardigheid nodig die je in je handleiding moet uitleggen?
- Maak een voorbeeld waarin je alle concepten en vaardigheden kunt gebruiken die je in deze handleiding wilt overbrengen. Maak het voorbeeld zo eenvoudig mogelijk.
- Definieer en schrijf de stappen om tot een eindresultaat te komen. Elke stap moet herhaalbaar zijn door je leerling.
- Filter alle uitleg, referenties, alternatieven en speciale gevallen eruit: zet deze in aparte artikelen.
- Schrijf een introductie. Wat leer je in deze handleiding? Vermeld de vereiste kennis of vaardigheden om de handleiding te kunnen volgen.
- Schrijf de samenvatting. Wat hebben we geleerd? Je kunt ook de volgende stappen vermelden om meer te leren.
- Voeg screenshots toe met annotaties om de acties die moeten worden uitgevoerd te illustreren. Tip: gebruik nummers in de screenshot en geef uitleg in de tekst. Dit maakt het makkelijker om je screenshot in vertalingen te hergebruiken en minimaliseert de inspanning om taal specifieke screenshots te maken.
- Voeg diagrammen toe om structuren, relaties en processen uit te leggen.
- Voeg de begeleidende artikelen toe met verklaringen, referenties en handleidingen.
- Zet alle artikelen van één onderwerp onder een overzichtsartikel, waarin wordt uitgelegd wat wat is, hoe ze zich verhouden en waar te beginnen.
Voorbeeld: Maak en publiceer een artikel in Joomla
Als voorbeeld maken we een handleiding over hoe je een artikel maakt en publiceert onder een menu-item in Joomla.
Informatie verzamelen
In onze gebruikershandleiding vind je relevante artikelen onder "Getting started", "Articles" en "Menus". Het is vaak verwarrend bij het beginnen met Joomla dat je geen artikel ziet nadat je het hebt gemaakt, hoewel je het als "gepubliceerd" hebt gemarkeerd. Om het artikel te zien, moet er een link naar het artikel zijn. Er zijn verschillende manieren om zo'n link te maken (zoals een menu-item, een categorie bloglayout of het plaatsen op de homepage bloglayout door het artikel als 'featured' te markeren of linken vanuit een ander artikel), maar we focussen nu op het beschikbaar maken van het artikel via een menu-item.
Concepten & Vaardigheden
We hebben 'inhoud', 'artikel', 'menu' en 'menu-item'. We moeten die termen verduidelijken. We tonen waar deze dingen te vinden zijn in het beheermenu. We laten 'categorieën' of 'featured' buiten beschouwing in deze handleiding.
Vereisten
Je moet toegang hebben tot het beheerdersgedeelte van een werkende Joomla-website en weten hoe je inlogt.
Doel
Ons doel is om te leren hoe je een nieuw Joomla-artikel maakt en een nieuw menu-item maakt waaronder we ons artikel plaatsen.
Stappen
Gebruik de volgende stappen om ons doel te bereiken:
A. Maak een artikel
Log in op je Joomla-beheerderspaneel.
Maak eerst het artikel. Navigeer naar het "Content" menu aan de linkerzijde en selecteer "Articles".
Klik op "New" om een nieuw artikel te maken.
Voer een titel en inhoud in voor je artikel.
Klik op "Save & Close" om je artikel op te slaan.
B. Maak een menu-item dat naar het artikel linkt
Om het artikel op de website te tonen, maken we een menu-item dat naar het artikel linkt. Navigeer naar het "Menus" menu aan de linkerzijde en selecteer "Main Menu".
Net als bij een artikel, klik je op "New" om een nieuw menu-item te maken.
Voer een titel in voor je menu-item. Dit is de titel zoals die in het menu zal verschijnen. Het hoeft niet hetzelfde te zijn als de titel van het artikel. Meestal is deze korter dan de titel van een artikel om beter in het menu te passen.
Selecteer een menu-itemtype: onder "Articles" selecteer "Single Article".
Selecteer het artikel: selecteer het artikel dat we net hebben gemaakt.
Ga naar de website en vernieuw de pagina. Gefeliciteerd: je kunt nu op het menu-item klikken om je artikel te zien.
Introductie
Schrijf de introductie: wat ga je leren in deze handleiding en welke vereisten zijn nodig.
Filter extra informatie uit
Kunnen we iets weglaten van wat er tot nu toe is geschreven? Wel, in stap 2 van het maken van een menu-item heb ik vermeld 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 weglaten voor nu. Maar het biedt een aanwijzing voor een meer gespecialiseerd artikel over artikel- en menutitel en wanneer ze worden weergegeven, met inbegrip van de algemene artikelinstellingen, de individuele artikelinstellingen onder het opties-tabblad, de menu-iteminstellingen onder het opties-tabblad van het menu-item en meer. Het zou ook goed zijn om een referentieartikel te maken over hoe artikelen, categorieën en menu-items samen werken; in zo'n artikel probeer je compleet te zijn en alle mogelijkheden op te sommen. Een gespecialiseerde handleiding zou kunnen zijn: "Hoe toon je de artikel titel?", waarin de instellingen in de algemene artikelinstellingen, de individuele artikelinstellingen en menu-iteminstellingen worden getoond. Een uitleg-artikel zou iets kunnen vertellen over de achtergrond waarom Joomla "artikel" gebruikt, terwijl bijvoorbeeld WordPress "bericht" gebruikt of hoe het artikel wordt weergegeven op de uiteindelijke pagina.
Conclusie
Rond alles af in een samenvatting. En vermeld enkele mogelijke volgende stappen om meer te leren (zoals een handleiding over het toevoegen van een categorie of een how-to guide over de sneltoets om naar het menu op te slaan).
Afbeeldingen en grafieken
Maak screenshots waarop de knoppen en velden die betrokken zijn bij het maken van een artikel en een menu-item zichtbaar zijn. Markeer de knoppen en velden die betrokken zijn.
Voor duidelijkheid kun je een diagram toevoegen dat laat zien hoe een artikel "onder" een menu-item wordt geplaatst.
Voeg referenties, handleidingen en verklaringen toe
Plaats alle extra informatie en instructies in aparte artikelen.
Overzicht
Als je meerdere artikelen over één onderwerp hebt, moet je een overzichtsartikel maken, waarin wordt uitgelegd hoe de artikelen zich verhouden en waar je moet beginnen.
Oefening
Begin met het maken van de bovenstaande handleiding over hoe je een artikel in Joomla maakt en publiceert. De beste manier om te leren is door te doen. We zullen een voorbeeld publiceren van hoe dit eruit kan zien in de huidige gebruikershandleiding (sandbox-site). Maar we zouden je versie daar graag plaatsen als je het huidige kunt verbeteren.
Dit artikel werd oorspronkelijk gepubliceerd in het Joomla Community Magazine.
Lees alle artikelen in het magazine via deze link
Joomla! bestaat al 19 jaar als Open Source project. Dat is een lange tijd in technologiejaren! 19 jaar geleden kon je niet eens een iPhone bezitten, of X gebruiken en waarschijnlijk had je geen Facebook-account maar een Hyves-account 😊.
Er is veel gebeurd, maar Joomla! is al die tijd een duurzame keuze gebleken als CMS voor miljoenen websites wereldwijd, ondersteund door een betrokken community.