2009-04-09

Dålig självinsikt

Saker som irriterar när man läser dokumentation:

- När det inte förklaras vad man ska ha det som beskrivs till. Visst, ni verkar ha ett fint API, men när är det meningen att jag ska använda det?
- När de vanligaste fallen inte ges företräde framför mer obskyra användningsområden. Så okej, nu vet jag allt om den här modulen, men jag ville inte veta allt, jag ville veta hur man gör en skitenkel grej.
- Frånvaro av exempel, så att diskussionen blir för abstrakt. Det känns som om man famlar efter något som man nästan förstår, men det är dimmigt och vagt i konturerna.
- Krystade Kalle Anka-exempel, som inte illustrerar faktisk användning. För att hålla exemplet så enkelt som möjligt så överförenklar man det, så att det knappt säger någonting.

Det svåra med att inte göra sig skyldig till de här misstagen är att det är svårt att förstå vad som är svårt med något man själv tycker är lätt. Ju mer generellt det är, desto svårare är det, vilket förklarar den översta punkten. För dig som skriver dokumentationen är det uppenbart i vilka fall man ska använda ett ModalWindow-objekt snarare än ett PromptDialog-objekt, men inte för n00ben på hörnet av kuben som sakta roterar runt, runt i ett okänt rum, eller snarare rymd, som jag föreställer mig som mörk, men inte helt svart. Det är som om det är svagt upplyst runt själva kuben, men man kan inte se speciellt långt i någon riktning, så man vet inte var man är, eller vad det är man är i, om det finns annat längre bort eller om det helt enkelt är tomt sen. Kanske finns det över huvud taget ingen mening med att spekulera i vad som finns där bortom, eller så är det det som är det viktigaste av allt, kanske hittar man gud där i mörkret, om man famlar sig fram. Samtidigt kan man fråga sig vad gud skulle göra i ett mörker enligt Swedenborg är gud andevärldens motsvarighet till solen i den fysiska världen så i någon mening så borde det lysa om gud och även om det är svårt att föreställa sig så borde ljuset vara så starkt att det inte spelar någon roll hur långt bort det är man skulle ändå se det fast i så fall skulle det inte finnas något mörker är inte hela problemet med de här monoteistiska religionerna just att de vill att gud ska vara allsmäktig det är det konceptet som pajar alltihop och det är inte som att det är nödvändigt för att man ska få till en schysst mysteriekult nej nu ska jag sluta blogga om dålig dokumentation och laga middag istället.

5 kommentarer:

Johan sa...

Vems dokumentation?

puterman sa...

Våran. Och deras. Allas. Utom den som redan är perfekt.

Olof sa...

Jag antar att du har haft en del krångel med Apples dokumentation. Symbians har jag hört inte alltid är så rolig, men där antar jag att själva API:t har mer grundläggande brister...

Microsofts svenska manual för Amiga Basic var rolig. Den engelska verkade ändå ha en del exempel, men i den svenska hade man bara klippt och klistrat en del källkod (exempelvis för det notoriskt kryptiska DEFFN) från något färdigt program, vilket ibland gjorde exemplet helt oförståeligt.

Även en del seriösa böcker om Amigaprogrammering nämnde Object Editor som ett seriöst verktyg för att editera BOB:s, vilket är ett annat slags exempel på dåliga instruktioner. Jag tror Datormagazin också nämnde programmet som ett hyfsat sätt att editera, kanske för att de inte ville trycka upp en listning med ett bättre. Med AMOS kom ett alldeles utmärkt program som hade typ 50 olika knappar och var lite svårt att förstå ibland, men det gick i alla fall att göra bra sprites med det.

puterman sa...

Apples dokumentation lider av alla de nämnda problemen. Ungefär som all annan dokumentation. Jag jobbar på en bok om documentation anti-patterns som kommer göra mig mer världskänd än the gang of four (oo nerds).

Olof sa...

Jag har boken om designpattern i min bokhylla. jag har lagt till alla viktiga design patterns i mitt program bibliotek där har jag också en jättehäftig xor funktion hejdå