Hvor stor er en fisk?



Hvor stor
er en
fisk?



y
g
g
d
r
a
s
i
l

2
0
0
2

Om disse sidene

Disse sidene er laget i forbindelse med et foredrag på Yggdrasil 2002, og er et forsøk på å beskrive hvilke typer henvendelser jeg får, og hvilke faktorer du bør tenke på når du skal gjennomføre et dokumentasjonsprosjekt. Du finner også noen tips til hvordan du velger verktøyene du vil bruke.

Merk: Hvis du bruker Opera, kan du benytte deg av en utmerket funksjon som heter OperaShow, og vise hovedpunktene på denne siden som en lysbildepresentasjon.

OperaShow starter du ved å trykke på F11, og så er det bare å bruke PageUp eller PageDown for å bla mellom lysbildene.

Hvis du av en eller annen merkelig grunn ikke bruker Opera, så kan du se et eksempel på hvordan sidene ser ut som lysbilder. Eller, hvis du er helt desperat etter lysbilder, men ikke vil bruke Opera, så kan du laste ned en presentasjon i PowerPoint-format.

Hvor stor er en fisk?

En del av forespørslene jeg får er av typen "Hvor stor er en fisk?". Jeg mener ikke at det er mange direkte spørsmål om fiskestørrelse, men at mange av henvendelsene er umulige å svare på; i hvert fall uten en god del tilleggsopplysninger. Noen "smårare" konkrete spørsmål blir det også innimellom:

  • Hvor mange sider bør det være i en håndbok for et økonomisystem?
  • Hvor mange A4-sider skriver du på en time?
  • Vi skal levere et stort system neste uke, kan du levere en Doc-To-Help-fil til da?
  • Hvor mange stikkord skal det være per side i en middels stor håndbok?
  • Hvor stor håndbok får jeg for 10.000 kroner?

Dette er den samme typen spørsmål som jeg selv stiller i andre sammenhenger, for eksempel når det blir snakk om bilverksted og slikt: "Det er en rar lyd på foran på venstre side. Kan det være klampen som har hengt seg opp?" Så jeg forsøker å svare etter beste evne uten å være for sarkastisk.

Men de aller vanligste spørsmålene (FAQ) er disse:

  • Vanlige kundetyper/prosjekter og spørsmål
  • Faktorer som påvirker omfanget
  • Når er prosjektet ferdig?
  • Verktøy

Kunder og prosjekter

Fra Til
Superstrukturert Totalt kaos

Kunder og prosjekter: Fellestrekk

  • Vanskelig å komme inn i prosjekter
  • Vanskelig å komme ut av prosjekter
  • Virkeligheten er ofte veldig forskjellig fra første forespørsel

FAQ

Vi har et program vi skulle hatt dokumentasjon til:

Bonusspørsmål: Kan vi bruke Doc-To-Robo?

Bonusspørsmålet skal jeg komme tilbake til. Når det gjelder de andre to spørsmålene, om pris og tid, har jeg to svar. Svar 1 er en tanke arrogant, og passer best hvis du skal forsøke å være morsom. Svar 2 er det mest presise jeg kan gi.

FAQ: Svar 1

Du kan få dokumentasjonen på tre måter...

...men du kan bare velge to av måtene samtidig

FAQ: Svar 2

Svaret er enkelt og greitt:

"Det spørs" er kanskje ikke det svaret de fleste vil ha, men det er i det minste presist.

I oppstarten av prosjekter går mye av tiden med til å få avklart de tingene som det spørs på. For noen prosjekter er det nok med et par, tre kontrollspørsmål. I andre tilfeller blir det et helt forprosjekt av denne prosessen. Alle faktorer er ikke aktuelle for alle prosjekter, og det er helt sikkert en mengde spesielle faktorer som bare er aktuelle for ett enkelt prosjekt. De neste avsnittene dreier seg om noen vanlige faktorer det kan spørs på.

Prosjektoversikt

  1. Avklar hva det spørs på
  2. Lag en plan
  3. Skriv innhold
  4. Evaluér prosjektet

Det spørs på: Tidsfrister

Den første hovedfaktoren for et prosjekt er en eventuell deadline. Hvis dokumentasjonen må være klar innen 14 dager, setter det jo en grense for hvor hva du kan klare å levere.

Ofte er det to tidsfrister i prosjekter:

Det beste er å bli enige om realistiske tidsfrister fra starten av. Det er slitsomt å forholde seg til stadig endrede sluttdatoer, både for den som skriver, og for den som venter på det endelige resultatet.

Det spørs på: Mengde

Hva og hvor mye du skal lage, er den andre hovedfaktoren for et dokumentasjonsprosjekt.

Det spørs på: Kvalitet

God kvalitet tar tid

Det krever mer planlegging, oppfølging og testing for å lage noe med god og varig kvalitet. En "quick & dirty" fiks kan kanskje være en billig løsning på kort sikt, men bli dyrt i lengde. Litt som å pisse i buksa for å holde varmen.

Høy produksjon er ikke nødvendigvis det samme som høy kvalitet. Det tar lenger tid å skrive kort og godt enn langt og dårlig.

Det spørs på: Formål

Hva er den egentlige grunnen til at du har fått i oppdrag å lage dokumentasjonen? Er det for å:

Uansett hva som er formålet med dokumentasjonen, er det greitt å få det avklart og definert før du starter på jobben. På den måten får verken du eller oppdragsgiveren urealistiske forventninger til sluttresultatet.

Det spørs på: Involvering

Dokumentasjonsdelen av dataprosjekter har en tendens til å komme i bakgrunnen av de fleste andre aktivitetene i prosjektet. For at du skal kunne levere noe som du er fornøyd med, er det viktig at du bruker tid på å komme ordentlig inn i prosjektet. Det kan for eksempel være smart å:

Det spørs på: Personressurser

I mange prosjekter er den største mangelvaren tilgang til andre personer. Forsøk å definere tidlig i prosjektet, og så konkret som mulig, hvor mye og hvor ofte du må ha tilgang til andre. "Jeg ønsker å intervjue programmerer X fra kl. 09 til 11 mandag 16. februar." Sørg også for å utnytte den tildelte tiden effektivt!

Listen nedenfor viser noen av personressursene du kan få nytte av i et dokumentasjonsprosjekt:

Det spørs på: Fysiske ressurser

Tilgang til maskiner og den slags er som regel ikke noe stort problem, men det er lurt å si fra på forhånd hva du har bruk for. Riktig verktøy er viktig, og ikke det første området det bør spares på, men mer om det senere. Med fysiske ressurser mener jeg ting som:

Det spørs på: Grunnlag

Mange av oppdragene mine går ut på å systematisere, formatere, samkjøre og språkvaske eksisterende informasjon, og snekre det hele sammen til håndbøker eller hjelpetekster. For eksempel finner jeg ofte nyttig informasjon i:

Det spørs på: Ymse

Til slutt spørs det på alle de "små" tingene som alltid tar lang tid, og som alltid kommer som en overraskelse på slutten av prosjektet:

Lag plan

Når du har funnet ut av alle ting som "det spørs" på, er det på tide å lage en dokumentasjonsplan:

Lag tilbud/overslag

Når jeg har definert en plan og fått den godkjent av oppdragsgiveren, er det enklere å lage et overslag over antall timer jeg kommer til å bruke, og hvilken timepris som er aktuell.

Som regel blir vi enige om et rammetimetall for prosjektet. Bruker jeg færre timer, blir det selvfølgelig billigere for oppdragsgiveren. Ser jeg at jeg nærmer meg slutten av timene uten å bli ferdig, melder jeg fra så raskt som mulig. I slike tilfeller tar vi ofte en ny runde og ser på årsaken til endringen i timetall, hvor mange flere timer som må til, hvem som skal ferdigstille resten av arbeidet, ny timepris, osv.

Fastpris går jeg sjelden inn på. Det er litt for mange faktorer i et prosjekt som jeg ikke styrer selv, så fastpris er bare aktuelt for veldig konkrete arbeidsoppgaver. For eksempel å lage et stikkordregister for en eksisterende håndbok.

  • Timepris
  • Fastpris
    • For mange ukontrollérbare faktorer
    • Kun veldig konkrete arbeidsoppgaver

Produksjon

Dette er den delen av prosjektet som tar mest tid, og som det handler minst om her. Bare noen få setninger om hovedpunktene i produksjonsfasen:

Når er du ferdig?

Programmererne har ofte noe de kaller "code freeze" når de skal avslutte et prosjekt. I ekstreme tilfeller skjer dette en sen kveldsstund fire/fem dager etter at den siste tidsfristen har gått ut. Alle sjekker alle filer inn i versjonskontrollsystemet, og så tar de en 20-minutters pizzapause. Straks tacopizzaen er fortært og den siste colaen er tømt, sjekker de ut filene igjen og starter de på neste versjon.

Det er ofte litt verre for en stakkars dokumentør. Naturlig nok så ferdigstilles dokumentasjonen etter at programmererne har gjort sitt, og det er ofte mange ting å få ferdig på kort tid:

  • All funksjonalitet som du visste om skulle bli laget den siste uka
  • All funksjonalitet som du ikke visste om
  • Alle endringer som du ikke har fått beskjed om
  • Trykking, distribusjon, etc.

Det første tegnet på at du ligger dårlig an, er når du hører denne setningen (enten fra deg selv, eller fra andre):

Den setningen betyr: a) Andre vet noe om dokumentasjonen som du ikke vet, for eksempel at det har kommet til en helt ny funksjon. b) Du vet noe om dokumentasjonen som andre ikke vet, for eksempel at du har bomma stygt på estimatene. Så hva kan du gjøre for å unngå å høre denne setningen?

Ferdig?: Planlegg nøye

Ferdig?: Meld fra underveis

Planer er blant annet til for at du skal kunne oppdage problemer tidlig, og det dummeste du kan gjøre er å vente med å si fra om forsinkelser til det er for sent å gjøre noe med det.

Det er en god idé å dokumentere hvorfor ting skjærer seg: "Intervjuet med programmerer X ble avlyst til fordel for andre aktiviteter Se vedlagt kopi av mail." Ikke bare for å skaffe seg ryggdekning, men også for å lære noe til neste versjon/prosjekt.

En annen god idé er å evaluere prosjektet etter at det er ferdig. Det behøver ikke å være en stor formell evaluering, men det er nyttig å tenke gjennom hva du har gjort riktig, og hva som kunne vært gjort bedre. Det er en fin måte å bygge opp erfaringen på, og erfaringen gjør at neste prosjekt (kanskje) blir litt enklere.

  • Si fra når du ser at det skjærer seg
  • Dokumentér hvorfor det går til h%¤#§¥

Ferdig?: Det blir enklere neste gang

  • Evaluér
  • Erfaring hjelper

Verktøy

For mange er valget av verktøy veldig viktig, og gjøres omtrent på religiøst grunnlag: "FrameMaker er alltid bedre enn Word". "Doc-To-Help er mye bedre enn RoboHelp til alt."

Min erfaring er at alle verktøyene har både sterke og svake sider og at det lønner seg å bruke dem til det de er best til. Bruk gjerne flere verktøy i kombinasjon med hverandre.

Når du skal velge verktøy, lønner det seg ofte å ta utgangspunkt i hvilke formater du har tenkt å levere.

  • Word og FrameMaker
  • RoboDitt og RoboDatt
  • Doc-To-Help og WordHelp
  • Author-IT og Help & Manual
  • En drøss andre

Verktøy: Velg format(er)

Og formater er det mange av, for eksempel:

Verktøy: Hvem skal skrive?

Mange av verktøyene krever ganske spesialisert kunnskap, så det er viktig å tenke på hvem som skal bruke verktøyene. Ikke bare i selve prosjektet, men også når dokumentasjonen skal vedlikeholdes. Ikke fall for fristelsen til å lage kompliserte ting bare fordi du kan. Hvis den som skal skrive, ikke har nødvendig tid og kompetanse, bør du velge et verktøy og en arbeidsmetodikk som tar høyde for det. Dette gjelder spesielt i løsninger som omfatter singlesourcing.

  • Kompetanse
  • Tid

Verktøy: Singlesourcing?

Singlesourcing, det vil si at du kan bruke (deler av) den samme kildeteksten i flere formater, er veldig populært blant de som skal betale for gildet. På papiret kan det se ut som du får to eller flere formater for samme prisen som ett format.

Faktum er at singlesourcing krever god planlegging og ofte mer oppsett i starten av et prosjekt. Det er ikke så enkelt at du kan ta en eksisterende håndbok, tømme den inn i et singlesourcing-verktøy og få det perfekte resultatet ut i andre enden. Eventuelle innsparinger ser du kanskje ikke noe til før i neste versjon av programmet du dokumenterer.

Et godt alternativ kan være å singlesource deler av dokumentasjonen, mens andre deler kun leveres i ett format.

Du kan for eksempel skrive "slik gjør du"-informasjon i Doc-To-Help og levere en håndbok i både PDF-format og den samme informasjonen som hjelpefil. Andre deler av dokumentasjonen, for eksempel feltbeskrivelser, kan du kutte ut fra håndbøkene. I stedet skriver du dem i RoboHelp og leverer dem bare som hjelpefil. Med litt planlegging kan du knytte sammen de to hjelpefilene og få dem til å se ut som én og samme fil.

Disse sidene er også et eksempel på singlesourcing. All teksten ligger i den samme filen, men ved hjelp av forskjellige stylesheets styrer jeg hvilket innhold som vises i tre ulike visninger:

  1. Den første visningen er vanlig visning på skjermen. Denne teksten her er for eksempel synlig på skjermen.
  2. Den andre visningen er ved utskrift til en skriver. Stort sett vises den samme teksten som på skjermen, men noe blir ikke skrevet ut, for eksempel menyen helt øverst på siden.
  3. Den siste visningen er i lysbildevisning i Opera. Når du viser en HTML-side i full skjerm i Opera, kan Opera samtidig skifte stylesheet. På den måten er det forholdsvis enkelt å forandre på layouten og å bestemme hva som skal vises, og ikke. Denne teksten er for eksempel ikke synlig i lysbildevisning. Litt flere opplysninger om lysbildevisning i Opera finner du i starten av dette dokumentet.
  • Må planlegges
  • Krever mer oppsett i starten
  • Alternativ:
    • Singlesource deler av dokumentasjonen
    • Kan noe av dokumentasjonen leveres i kun ett format?

Verktøy: Andre faktorer

Det er også mange andre faktorer å ta med i valget av verktøy:

Verktøy: Pekere

Det finnes en drøss av verktøy, og det er ikke alltid enkelt å velge. Linkene nedenfor gir deg en ganske god oversikt over de vanligste verktøyene:

Viktigst: Innhold

Et spørsmål jeg får noen ganger er:

"Kan du anbefale én ting som vil gjøre dokumentasjonen vår bedre?"

På tross av at det meste på disse sidene dreier seg om den mer tekniske delen av det å skrive datadokumentasjon, er svaret ganske enkelt:

Og for å lage bedre innhold er det øvelse som skal til. Det skader heller ikke med et skrivekurs, for eksempel fra Nils Petter Smeby på klartekst.no.