Hieronder staan een aantal richtlijnen die de betrouwbaarheid, leesbaarheid en 'vorming' van je documentatie verbeteren.
Test voorbeelden om er zeker van te zijn dat ze werken (gebruik knippen en plakken om je shell de exacte bewoording uit de manpage te geven). Kopieer de uitvoer van je opdracht in je manpage, typ niet slechts in wat je denkt dat je programma zal afdrukken.
Proeflees het, pas de spellingscontrole erop toe en laat iemand anders het lezen, vooral als Engels je moedertaal niet is. De HOWTO die je aan het lezen bent heeft de laatste test doorstaan (speciale dank aan Michael Miller voor een nogal heldhaftige bijdrage! Alle resterende ruwe kantjes zijn geheel mijn fout). Extra vrijwilligers zijn altijd welkom.
Test je manpage: Produceert groff foutmeldingen wanneer je je manpage formatteert? Het is aardig als je de groff opdrachtregel in een commentaarregel plaatst. Produceert de opdracht man(1) foutmeldingen wanneer je man jeprog aanroept? Produceert het 't verwachte resultaat? Zullen xman(1x) en tkman(1tk) met je manpage overweg kunnen? XFree86 3.1 heeft xman 3.1.6 - X11R6, het zal proberen te decomprimeren met gzip -c -d < %s > %s zcat < %s > %s
Zal makewhatis(8) de éénregelige beschrijving uit de NAAM sectie kunnen extraheren?
Zet je manpage om in HTML opmaak met behulp van rman van http://polyglotman.sourceforge.net/, en bekijk het resultaat met een set webbrowsers (netscape, mozilla, opera, lynx, ...) Controleer of de kruisverwijzingen tussen je manpages als hyperlinks in de gegenereerde HTML functioneren. Als er een website bestaat voor je softwarepackage, plaats daar dan de manpages, en houd ze bijgewerkt.
Het utility rman kan manpages ook omzetten naar LaTeX, RTF, SGML en andere formaten; kijk deze na als je je manpages in een boek of ander groot document wilt opnemen.
Probeer je manpage om te zetten in HTML met behulp van man2html, wat al sinds man-1.4 onderdeel uitmaakt van het Linux man-package. Het man2html utility is een minder grootse vertaler dan rman, maar vrijwel elke Linux gebruiker heeft het al, dus het is het waard te zorgen dat man2html zich niet verslikt in je manpage.