Hvordan tester du din dokumentation?

Jeg har det seneste stykke tid siddet og testet op til vores kommende release, og noget af det, der også altid skal checkes, er vores dokumentation. Som det gælder for al anden test, er den sjoveste form for test, når man kan automatisere sig fra at skulle gøre det samme næste gang...

Vores dokumentation (brugervejledninger, tutorials m.m.) ligger primært som DocBook XML-filer, der bygges til en online, HTML-baseret hjælp, og så har vi noget referencedokumentation i ren HTML-format, der ryger ind i samme online-hjælp.

Da vi lever af at lave et produkt til web-automation, har jeg valgt at bruge den crawler, der er indbygget i vores produkt til at gennemsøge hjælpen og checke for, om alle de interne links er gyldige, og om alle billeder (primært screenshots og ikoner), der er lagt ind i hjælpen, findes. Naturligvis kunne man også have brugt andre crawlere til formålet, men vi kan jo ligeså godt spise vores egen hundemad...

Jeg fandt faktisk en del fejl, da jeg første gang kørte crawleren, inden vi releasede den foregående version. Siden har den ikke gjort meget væsen af sig, men det er trygt at vide, at den kører som en del af det natlige build og passer på de små HTML-filer. ![Eksternt billede](http://www.version2.dk/uploads/smil3dbd4d6422f04.gif" alt=")

Det næste, jeg kunne tænke mig, var at få strikket en test sammen, der automatisk kunne lave (engelsk) stavekontrol på hjælpen. Til dette release har jeg siddet manuelt og klippe-klistret tekst fra dusinvis af filer ind i Word for at få det checket, og det var faktisk jævnt kedeligt - især fordi jeg ved, at vi bliver nødt til at gentage det næste gang, hvis ikke vi finder på en smartere løsning. Suk.

Så hvad gør I derude for at få regressionstestet jeres hjælp' Og er der nogen, der sidder med et godt bud på, hvordan man får lavet sig en automatiseret stavekontrol på en stor flok HTML-dokumenter'

Kommentarer (12)
sortSortér kommentarer
  • Ældste først
  • Nyeste først
  • Bedste først
#3 Jesper Louis Andersen

Aspell med den lokale ordbog i repository er ikke en dårlig ide. Og så et target i build-systemet. Hvis man har fascistiske tendenser kan man tvinge alle docbook commits til at skulle overleve stavekontrolchecket, men det synes jeg personligt er den forkerte fremgangsmåde.

  • 0
  • 0
#5 Nikolaj Brinch Jørgensen

Du kan evt. transformere dine XML dokumenter til et format som allerede er kendt af en spell checker (open office har allerede stavekontrol og kan automatiseres). I hvert fald skulle du på den måde kunne bygge bro mellem din XML og en automatiseret spell check.

PS: Open Office er blot et eksempel, men en hvilken som helst spell check motor som kan gøre det (med mulighed for failure og reporting) kan bruges, så længe du kender formatet der skal ind i den (rå text filer kan du fleste programmer jo spise), og så XSLT din XML til formatet.

  • 0
  • 0
#9 Anne-Sofie Nielsen

Hej Peter,

Nu er det ikke mig, der har lavet vores DocBook-opsætning; jeg har kun fyldt indhold i manualerne hist og pist... Så jeg vil se, om jeg kan overtale min kollega Arne, som er den, der har rodet med DocBook hos os, til at skrive en kommentar.

Tidligere lå vores dokumentation i Word-format, hvilket havde en del væsentlig ulemper, så af den årsag har jeg kun oplevet overgangen til DocBook som en fordel. :-) Nå ja, måske med den undtagelse, at der så ikke længere automatisk er stavekontrol, men det er jo så det, jeg arbejder på at gøre noget ved nu...

Hilsen Anne-Sofie

  • 0
  • 0
#10 Anne-Sofie Nielsen

Nu er det faktisk lykkedes mig at få skruet en ganske nydelig JUnit-test sammen ved brug af Jazzy: http://sourceforge.net/projects/jazzy/

Den arbejder på HTML-udgaven af vores dokumentation (som dels kommer fra HTML filer, dels fra DocBook XML-filer med diverse makro-erstatninger af f.eks. produktnavn), som jeg så stripper for markup, ampersand-decoder og fjerner ...-blokke i (der indeholder kodeeksempler).

Derefter sparkes Jazzy afsted, og eventuelle stavefejl rapporteres som at JUnit-testen fejler.

Jeg har brugt de ordbøger, som ligger på Jazzy-projektets side, og så har jeg lavet en ekstra ordbog med de ord, som den ikke kendte, men som var nødvendige, f.eks. "dashboard", "download" og "Google".

Hvis der er rigtig mange ord i ens dokumentation, som ikke er i ordbøgerne, kan det være en fordel at starte med at generere ordlisten udfra de ord, testen melder som fejl, og så gennemgå dem for at se, hvilke der faktisk er fejl og hvilke, der bare er f.eks. tekniske termer, som den ikke kender.

Og så har jeg selvfølgelig fået rettet en hel del stavefejl i vores dokumentation. :-)

  • 0
  • 0
#12 Anne-Sofie Nielsen

Hej Nikolaj,

Jeg vil ikke kalde det et decideret "test framework". Udover at bruge Jazzy-klasserne + ordbøgerne derfra, har jeg en enkelt Junit-klasse, hvoraf en hel del af koden går ud på at finde det rigtige sted at hente HTML-filerne fra.

Det er supernemt at bruge Jazzy, og der er nogle gode eksempler med, når man downloader den. Dvs. at ens Junit-testklasse bare skal kalde spell checker'en på den/de filer, der skal testes, og så giver man den et callback med, hvor man passende kan kalde JUnits fail()-metode, hvis der er fejl.

Mvh. Anne-Sofie

  • 0
  • 0
Log ind eller Opret konto for at kommentere