Den Forbandede Dokumentation

Jeg gider ikke engang skrive den obligatoriske indledning, I kender den til hudløshed.

Som en udløber af vores "Varnish User Group" møde i Amsterdam, er jeg ved at kigge på hvad vi gør ved vores dokumentation og derfor har jeg surfet rundt i alle mulige open source projekter for at snuse til hvad de gør.

Hvis jeg skal være lidt grov, har jeg kun fundet et eneste projekt der har tænkt seriøst over problemet og/eller gjort noget intelligent ved det: Python.

Python skriver dokumentationen som .txt filer og har en postprocessor der kan spytte HTML, XML, LaTeX osv ud.

Forskellen fra alle andre postprocessorer, fra NROFF, TeX og fremefter, er at text-filen i aller højeste grad selv er læselig, idet den "markup" man bruger, næsten er den samme som vi kender fra UseNet News, email og BBS.

En af grundene til at jeg aldrig har kunnet arbejde med {La}TeX eller DocBook, er at jeg ikke kunne se teksten for markup. NROFF/Troff er marginalt bedre, fordi markup i langt mindre grad ligner tekst, hvilket så til gengæld har masser af andre ulemper.

Løsningen på dette er traditionelt at bruge en særlig grafisk editor, men det åbner bare en helt ny række problemer, startende med at få skidtet installeret, dernæst ventetiden på at launche editoren når man skal skrive og sluttende med at værktøjet med usvigelig sikkerhed ikke kan lave output i en .txt fil der er til at læse.

Og deri ligger tilsyneladede Python folkenes vigtigste indsigt: .txt formatet er lingua franca for dokumentation og samtidig den mest restriktive typografi, derfor skal den være kildeteksten.

Prisen for dette valg, er at man ikke kan ansætte en grafisk designer, for der er ikke noget design at lege med og man kan heller ikke lave alle mulige grafiske trick og sidespring.

Men som John Postel beviste med RFC'erne: 95 tegn er faktisk rigeligt til både hvem som helst og hvad som helst.

Jeg tror Varnish adopterer "reStructuredText", det ligner noget der har en chance for at der kunne blive skrevet noget dokumentation.

phk

Kommentarer (17)
sortSortér kommentarer
  • Ældste først
  • Nyeste først
  • Bedste først
Troels Arvin

Mit foretrukne dokumentationsform er at skrive i en wiki. Men reStructuredText (som nogle åbenbart forkorter til ReST, hvilket nok skal skabe forvirring af og til) ser rigtignok godt ud.

Mit problem med GUIer er ikke installation og den slags. Det er, at WYSIWYG-editering typisk resulterer i et helvede, når man vil se, hvad der indholdsmæssigt har ændret sig mellem versioner: Alverdens layoutmæssige ligegyldigheder blander sig med essensen.

  • 0
  • 0
Troels Arvin

I øvrigt: Varnish har godtnok fået sig endnu en imponerende reference: collateralmurder.com, som må have været én af den forløbne ugers travleste sites, synes at have været Varnish-robustgjort fra starten -- og det har de tilsyneladende holdt fast i.

  • 0
  • 0
Poul-Henning Kamp Blogger

Du har fuldstændig ret med hensyn til ændringerne, hvis ikke man kan lave en meningsfyldt diff(1) er det ikke værd at røre ved.

Men det var lidt underforstået fra min side, for hvis jeg ikke kan grep'e dokumentationen, så kan det være inderligt ligegyldigt til at begynde med, og med grep-abilitet følger diff-abilitet og muligheden for at checke det ind i et versionsstyringsværktøj.

Poul-Henning

PS: Ja, wikileaks adopterede varnish meget tidligt, det passer perfekt til deres trafikprofil: sjældne opdateringer som Gud og hver mand vil se.

  • 0
  • 0
Peter Valdemar Mørch

Jeg har også kigget på markup muligheder.

reStructuredText, Markdown, textile, asciidoc minder lidt om hinanden. Efter at have (brugt alt for lang tid på at have) studeret dem alle, er jeg selv tilhænger af og bruger asciidoc.

Men er glad for at se, at der er andre end jeg, der er glade for tekstfiler til at skrive dokumentation i!

For mig er det vigtigste at det hele foregår i den samme editor.

Peter

  • 0
  • 0
Poul-Henning Kamp Blogger

Jeg kender udemærket doxygen og bedømt på det gennemsnitlige resultat, en automastisk produceret liste af variabler, functioner, klasser og filer, er det ikke meget bevendt.

Doxygen er også primært vendt imod dokumentation af en kildetekst, jeg har brug for noget der også kan skrives uden direkte reference til kildeteksten, f.eks en "tutorial" type dokument.

Poul-Henning

  • 0
  • 0
Bryan Østergaard

Exherbo har altid fulgt princippet om at dokumentation skal være nem at skrive og vedligeholde og at der ikke må være "krav" om special værktøjer.

I Exherbos tilfælde faldt valget så på Markdown, men det er i bund og grund underordnet. Det vigtige er at nye folk trivielt kan hjælpe med dokumentationen og at gamle folk på projektet også skal bruge minimalt energi på opdateringer.

I samme ånd så har vi skrevet en triviel Makefile der generer HTML-koden ud fra Markdown filerne og bliver kørt som et cron job på webserveren. Så bliver det ikke meget nemmere :)

  • 0
  • 0
Troels Liebe Bentsen

Syntax'en er ikke alt for grim(http://www.dokuwiki.org/syntax) og så arbejdes der direkte på filsystemet uden at bruge en database.

Det vil sige man kan gøre sin HTML udgave af dokumentationen skrivbar/kommenterbar, og så holde styr på ændringerne med git eller et andet værktøj.

I sidste ende handler det om at det er nemt for folk at rette fejl i dokumentationen eller i det mindste kommentere på fejl og mangler. Som man fx. gøre i PHP's dokumentation, hvilket lader til at fungere fint.

  • 0
  • 0
Poul-Henning Kamp Blogger

Der findes en del foo->HTML markups, men de fleste af dem, herunder docuwiki, har ingen anden backend, og dermed er PDF produktion i praksis ikke muligt.

(Nej, jeg vil ikke producere PDF ved at printe med firefox)

Poul-Henning

  • 0
  • 0
Martin Kofoed

Vi er lige gået over til at versionere al vores dokumentation sammen med sourcekoden. Vi gør det i tekstfiler med wiki-syntax (Confluence-dialekt), som så bliver lagt i Subversion sammen med alle andre projekter. Vores bygge-scripts sørger derefter for at generere HTML samt flytte dette til en webserver som en del af build-processen.

Resultatet er, at dokumentationen altid følger de taggede releases. Samtidig checker man altid dokumentationen med ud. Det ligger som et .docs-projekt sammen med web, ejb, ear og andre. Det er med andre ord umuligt at ignorere.

WikiText er en del af Mylyn, som kommer med eclipse. Der er sågar en editor med preview-funktion med i pakken ...

Udfordringen er, at man selv skal holde styr på referencer for ikke at ende med 404'ere. Der er jo ingen database til at sikre den slags. Vi overvejer at bygge "et eller andet" til at gøre det. Og så skal man lige bruge lidt tid på at lave stylesheet, så outputtet kommer til at se rimeligt læsbart ud.

Det handler om at gøre det NEMT for udviklere at skrive dokumentation. Ellers bliver det enten ikke skrevet ordentligt eller måske slet ikke skrevet overhovedet. Og så skal det være brugbart fremadrettet: man skal føle, at andre får brug for det, man laver. Word-dokumenter er typisk "write-and-forget", der skrives, fordi man skal. Det passer typisk udviklere rigtigt godt at slippe for Word og lignende.

  • 0
  • 0
Ulrik Rasmussen

Gitit er en wiki der ligesom dokuwiki gemmer sine data i filsystemet, men til gengæld kan bruge git, darcs eller mercurial til revisionsstyring, så du ikke er tvunget til at bruge HTTP-frontend'en til at rulle ændringer tilbage.

Derudover bruger gitit Pandoc, så du kan skrive al din dokumentation som reStructuredText, og derefter konvertere til HTML, ODF, PDF, LaTeX, Markdown, osv.

Og så er det skrevet i Haskell :)

http://hackage.haskell.org/package/gitit

  • 0
  • 0
Lars Lundin

"Jeg kender udemærket doxygen og bedømt på det gennemsnitlige resultat, en automastisk produceret liste af variabler, functioner, klasser og filer, er det ikke meget bevendt.

Doxygen er også primært vendt imod dokumentation af en kildetekst, jeg har brug for noget der også kan skrives uden direkte reference til kildeteksten, f.eks en "tutorial" type dokument"

Ja, doxygens output synes jeg heller ikke meget om.

Jeg er nu alligevel glad for at vi bruger det på arbejdet:

1) Doxygen har et meget lille og rent ASCII "mark-up overhead".
2) Dokumentationen står i et velstruktureret standardformat, som jeg finder vældigt let at læse direkte i kildeteksten (og med min editor hopper jeg nemt hen til funktions-definitionen, hvor teksten står lige ovenfor).

  • 0
  • 0
Jesper Louis Andersen

Derudover bruger gitit Pandoc,...

Jeg er også ret glad for Pandoc. Det er læseligt som råtekst, det kan producere HTML og LaTeX og du kan have den dokumentation du end måtte have i et råt format som du kan lave "git grep" eller lignende på.

Klart anbefalelsesværdigt!

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