Tydliga tekniska förklaringar

Teknisk dokumentation ska gå att förstå utan att läsaren måste gissa vilken version, indata eller miljö du utgick från. Börja med frågan läsaren vill besvara. Visa sedan ett litet korrekt exempel och förklara de detaljer som behövs.

Gör vaga påståenden användbara

Vagt: “Binärsökning är snabbare.”

Bättre: “I en redan sorterad array gör binärsökning O(log n) jämförelser i värsta fall. Den kräver indexerbar data och räknar inte med kostnaden för att först sortera indatan.”

Vagt: “Använd Git för att uppdatera din gren.”

Bättre: “Kontrollera aktiv gren och lokala ändringar med git status. Hämta sedan fjärrändringar och integrera rätt standardgren enligt teamets arbetsflöde.”

Bra förklaringar anger antaganden, definierar indata och skiljer asymptotisk analys från faktisk benchmark.

Ett fokus per sida

Använd rubriker för syfte, förutsättningar, mekanism, exempel, avvägningar, kontroll och vidare läsning. En referens kan fokusera på exakta signaturer; en handledning på räkneexempel. Upprepa inte generell teori överallt när en central översikt redan förklarar den.

Skriv för underhåll

Beskriv beteenden som går att kontrollera i stället för att bara kalla något “bättre”. Vid instruktioner som ändrar ett system behövs en säker kontroll och ibland rollback. Publicera aldrig känsliga infrastrukturgifter i öppna dokument.

Övning: Skriv om “den här koden är optimerad” till ett mätbart påstående. Vad mättes, med vilken indata och under vilka förhållanden?

Fortsätt med Markdown och README-filer.