Recommended
More Related Content
Featured
Featured (20)
Systemdokumentasjon med Markdown og Asciidoctor.
- 1. menneskene utgjør forskjellen Systemdokumentasjon med Markdown og Asciidoctor. Michael Gfeller
- 2. menneskene utgjør forskjellen Systemdokumentasjon med Markdown og Asciidoctor. Michael Gfeller
- 6. LIVSLØP
- 8. 8 MARKDOWN “HTML is a publishing format; Markdown is a writing format.” John Gruber
- 12. OPPSUMMERING
Editor's Notes
- Systemdokumentasjon er en nødvendighet som sjelden vekker stor begeistring hos de som skal skrive den, heller ei hos de som skal lese den.
- Hvorfor er det sånn? Det skyldes ikke bare fordi det er morsommere å skrive kode, men også fordi det kan være utfordrende å vite hva dokumentasjonen skal inneholde, hvor mye som er godt nok, og hvordan den skal håndteres og leveres. Å skrive god dokumentasjon er krevende. Det er mye enklere å fokusere på innholdet når format og verktøy er forfattervennlig og resultatet brukervennlig. Jeg heter Michael Gfeller, jeg er utvikler og arkitekt, arbeider i et prosjekt hvor målgruppene av det vi lager også er utviklere og arkitekter. Det er avgjørende at vår systemdokumentasjon er så bra at andre både liker å lese den og lett kan bruke vårt produkt. Confluence, som vi brukte for de fleste delene av systemdokumentasjonen, opplevdes ikke som optimalt. Bl.a . var eksport til PDF og versjonering alltid en smertefull opplevelse. Vi måtte gjøre noe med dette, og jeg skal i dette foredraget fortelle om hva vi kom fram til og kan anbefale.
- Dokumentasjon står på 3 søyler: forfatter, innhold og leser. La oss ta en titt på de.
- Her ser vi resultatet av en liten intern spørreundersøkelse om hvilke roller som er relevante ifm systemdokumentasjon. Forfatter og leser har stort sett de samme teknisk orienterte rollene, som bl.a utvikler, arkitekt, driftansvarlig, og produkteier. Derimot er salg og marketing, kontraktansvarlig og sluttbruker ikke roller som er relevante for systemdokumentasjonen.
- Når det gjelder innhold har vi nok en klar idé hva system betyr for oss: det er synonymt med løsning eller produkt. På den andre side er det kanskje ikke så opplagt hvilke typer dokumenter systemdokumentasjon består av. Her vises resultatet av samme intern spørreundersøkelse om innholdet av systemdokumentasjonen, kombinert med informasjon jeg fant på nettet. En interessant forskjell mellom det jeg fant på nettet og det som kom fram internt, var at de fleste definisjoner jeg fant på nettet inkluderte krav som viktig del, men ikke løsningsbeskrivelser. Jeg er nok enig i det. Løsningsbeskrivelser beskriver jo ikke nødvendigvis det som faktisk ble implementert til slutt. Det som ikke finnes i denne listen er salgs- og markedsdokumenter, kontrakter, og oppgaver fra Jira eller lignende smidige verktøy.
- Systemdokumentasjonens livsløp følger ganske enkelt livsløpet og livsfaser av våre produkter og løsninger. Livsløpet begynner med kravspesifikasjon, og slutter med avvikling. Livsfaser kan tilsvare sprinter, delleveranser og leveranser.
- Velvalgt format, verktøy og infrastruktur gjør det mer gledelig for forfattere å holde dokumentasjonen oppdatert og følge produktets livssyklus. Det skal være enkelt å skrive og produsere dokumentasjon, det skal være enkelt å finne forskjeller mellom versjoner, og det skal være enkelt å kunne verifisere at og når dokumentasjonen har blitt oppdatert. Med andre ord, det skal være mulig for oss å jobbe med dokumentasjon som vi jobber med kode. Formater og verktøy som Word eller Confluence og tilordnet infrastruktur egner seg ikke til dette, mens tekstformat, bygge- og konverteringsskript og versjonskontroll er mye bedre.
- Når man begynner å undersøke mulige formater, støter man ganske raskt på Markdown. Det er kanskje mest kjent som GitHub Flavoured Markdown. Markdown ble utviklet i 2004 av John Gruber, og betegner både formatet og et Perl-skript som generer HTML. Hans hovedformål var å skape et tekstbasert format som var enkelt å skrive og lese. Et enkelt Markdown-dokument vises her. Strukturelementene er typiske og de fleste av oss gjenkjenner denne stilen. Det finnes mange varianter og utvidelser av Markdown, men det opprinnelige formatet har ikke endret seg. Markdown er bra, men vi hadde behov for mer. Bl.a. ønkset vi mulighet for å dele opp dokumentasjonen i flere filer, og for å kunne bygge opp nye dokumenter fra slike deldokumenter. Andre krav var automatisk innholdsfortegnelse, callout i kode, admonition blocks, betinget tekst, og overføring av kontekstvariabler til prosesseringsmotoren under publisering av dokumentasjonen, f.eks. for å kunne sette versjonen. Selvsagt måtte det også være bra verktøystøtte, god dokumentasjon, utbredd bruk og et aktivt miljø. Verktøyet skulle passe godt inn i vår utviklingsinfrastruktur, slik at det ikke oppsto behov for installasjon av nye verktøy på utviklermaskinene. Konkret betyr dette bl.a. at Maven skulle kunne brukes for å generere dokumentasjonen, uten at det måtte være nødvendig å installere noe i tillegg.
- I evalueringsprosessen så jeg litt nærmere på GitHub flavoured Markdown, som jeg syntes var for enkelt og begrenset for våre formål. Jeg tok også en titt på Pandoc. Pandoc kan oversette mellom mange forskjellige formater, og har også en egen variant av Markdown med mer funksjonalitet enn det opprinnelige formatet. Men det ser ikke ut at Pandoc støtter deldokumenter, eller at det finnes en Pandoc maven-plugin. En viktig aktør i dette landskapet er Asciidoctor. Ifølge Dan Allen, Asciidoctor Project Lead, har Asciidoctor utviklet seg til en kritisk komponent for dokumentasjon, spesielt innen open source software. Asciidoctor er moden, forbedres kontinuerlig og brukes av mange. Asciidoctor tilfredstilte våre behov, og vi valgte det som format og verktøy. Asciidoctor er implementert i Ruby og kan derfor kjøres på JVM’en. Det finnes en oppdatert Maven-plugin som fungerer veldig bra, og ordner alt. Asciidoctor kan publisere i HTML, DocBook, PDF, og deck.js med flere.
- På venstre siden ser vi et enkelt Asciidoctor dokument med de elementene jeg nevnte tidliger: innholdsfortegnelse, import av et deldokument, admonition block, kildekode med korrekt syntaksmerking og callout. På høyre siden vises tilsvarende HTML-side.
- Vår verktøykjede ser slik ut: dokumentasjonen skrives i Asciidoctor-format, og prosesseres med tilsvarerende Maven-plugin. Mercurial brukes til versjonskontroll. Jenkins som byggeserver utruller kontinuerlig HTML til en Nginx tjener. Som redigeringsverktøy brukes hovedsakelig IntelliJ og Brackets. Begge støtter Asciidoc og tilbyr mulighet for forhåndsvisning.
- Vi har sett at systemdokumentasjon kan eller bør inneholde informasjon fra krav til drift. Den skrives av personer som har teknologinære roller, og leses av personer med lignende roller. Asciidoctor er både et format og et verktøy som passer godt inn i utviklerens infrastruktur, og gjør det enklere og mer gledelig å skrive og vedlikeholde systemdokumentasjon. Ikke alle deler av systemdokumentasjonen må skrives i samme format. Vi har blitt lykkeligere forfattere med Asciidoctor.
- Takk for oppmerksomheten!