De 10 budene for dokumentasjon

Toyota er kjent som den mest effektive organisasjonen på planeten utenfor menneskekroppen, og en av deres filosofier er å unngå dokumentasjon. I stedet for å lage en "prosess" for når noen på forsamlingslinjen trenger flere bolter, har de bare 5 fat bolter på hyllen, og når en er tom flytter den den fra hyllen og noen kommer hver time og fyller på hyllene fra baksiden. Det er ikke nødvendig å dokumentere noe, prosessen gjør det for deg.

Det var en Nylig artikkel om kvarts som snakket om Apples oppmerksomhet til sjekklister.

Det viser seg at nøkkelen til Apples kreativitet, fart og tilpasningsevne er på overflaten, det nøyaktige motsatte av den slags frihjulende kreativitet man kunne forvente. Det er en sjekkliste ... en veldig lang en.

Som fikk meg til å tenke på hva min filosofi om sjekklister er. Det er mye galt med sjekklister. De blir utdaterte. De kan være lange og kjedelige og repeterende. Som alle målinger kan de fokusere på feil ting. Men alle disse tingene er sanne for å hoppe over sjekklister også, ikke sant? Jeg mener den tredje gangen du har gjort samme feil, det er nok tid til å innrømme at etter en sjekkliste kan du ha spart deg tid.

Men sjekklister er bare gode hvis de gjelder, og de oppdateres ofte, og du er fortsatt på innfall av et menneske som, la oss innse det, er ikke bygget for å være perfekt hele tiden.

Virkelig verdensproblem

Vi har en standard Drupal installere vi starter med for de fleste klienter som er på Drupal. Dette inkluderer moduler, innstillinger, standardbrukere og standard testdata. Det pleide å være en sjekkliste, men det var alltid utdatert. Deretter gikk noen inn og gjorde det så konkret at alle med begrenset kunnskap om Drupal kunne gjøre det, så alle de dørharde Drupal-folkene i butikken hatet det, så vi tok det ut, og da kunne vi ikke trene noen nye på det og bare senior Drupal devs kunne følge det, så da begynte vi hardt å kode det inn Drush.

Drush betyr at alle med Drupal-opplevelse kunne kjøre et par linjer med kode og alt ville "skje" magisk. Ikke mer "menneskelig feil", det er en sjekkliste, men i stedet for et rotete menneske som prøver å følge en sjekkliste fulgte en datamaskin den.

Problemet med det var at selv den enkleste forandringen trengte en utvikler og hver forandring måtte testes og så falt det ganske raskt.

Til slutt kom vi over den åpenbare løsningen, noe som er noe hardkodet i Drush, noe som gjorde det litt vanskelig å endre.

Nå har vi bare et nettsted som heter "klone meg" eller noe slikt, og når vi har en ny klient, dupliserer vi det bare. Endre det pleide å involvere en programmerer og mye annet arbeid, nå kan alle som har passordet på teamet, gå og endre noe. Hvis en designer ønsker forskjellige testdata, endrer de det, og det vil automatisk være i vårt neste prosjekt. Hvis en PM bestemmer at vi trenger en annen standardbruker for opplæringsformål, oppretter de en og det vil være i vårt neste prosjekt.

Vi var heldig nok til å ha Gavin her på Gravity Switch i noen år. Han bidro ganske mye til vår kultur og vår kode, men hans visdom om når "hack" ting og når man skal prosedyre dem er noe som egentlig har forandret hvordan jeg nærmer seg dokumentasjon.

Gavin lærte oss at god kode er selvdokumenterende.

De 10 budene om dokumentasjon

1. Du skal ikke overdokumentere - Hvis det tar lengre tid å dokumentere enn å gjøre, er du overdokumentert.
2. Du skal automatisere før dokumentet - Ta ut den menneskelige faktoren når det er mulig.
3. Du skal ikke rive gjennom det samme tre ganger - Hvis du har slått opp eller måtte finne ut det samme to ganger, er det på tide å prosedyre.
4. Hvis det kommer til å mislykkes, gjør det sviktet stort . De vanskeligste tingene er de tingene du savner den første (og til og med 10.) tiden du vurderer dem. Hvis du har et valg mellom å lage en prosess som vil stoppe forsamlingslinjen eller krasje nettstedet ditt hvis det mislykkes eller en som vil skape en liten feil, velger du alltid "ta ned nettstedet" fordi du minst vil se problemet første gang .
5. Du skal sette prosessen der man må reise over det - fordi den må bli funnet.
6. Eie det - Når du følger en prosess, vær oppmerksom på at jobben din er å produsere det beste resultatet. Det er ikke å følge prosessen. Alltid nærme det med skepsis og se kritisk på resultatene.
7. Innrøm når det ikke fungerer - Noen ganger kan det se ut som det er, men det er det ikke. I vår verden trenger vi alltid standard testdata, men prosessen for å lage det i WordPress er helt annerledes enn å skape den i Drupal, så vi trenger helt forskjellige prosesser.
8. Løs det raskt - Hvis prosessen din er utdatert, ikke bare ignorere problemet og vinge det, eller velg og velg delene du vil følge. Løs det når du går. Det vil bare ta deg minutter å gjøre i de fleste tilfeller, og disse minuttene blir til timer neste gang du eller noen andre bruker prosessen.
9. Velg dine kamper - Steve Krug (bruken av brukbarhet) sier at du bør teste ofte. Finn ditt største problem. Gjør det minste arbeidet du kan gjøre slik at det ikke lenger er ditt største problem, og gjenta deretter. Du prøver ikke å få noe lite ut av systemet, du prøver å få hele systemet til å løpe bedre.
10. Revisit - Hvis du har brukt en prosess et dusin ganger og ikke har endret det, bør du tenke på hvordan du kan gjøre det mer effektivt, eller hvis du bare skal automatisere det.

• ← Hvordan designe for mobile enheter, når du ikke har en
• Slik optimaliserer du ditt nettsteds destinasjonsside for mobil →