Uppskattad lästid: 6 minuter
Vi har nyligen lanserat en ny dokumentationsplattform som är en omfattande och pålitlig informationskälla för alla våra kunder. Personerna bakom verksamheten är vårt utbildningsteam, lett av Florian Haas, som nyligen gav värdefulla insikter i projektets utvecklingsprocess i en intervju. Den här artikeln är en sammanfattning av de breda penseldrag som ligger bakom teamets arbete under projektets gång. Om du vill lära dig mer om den tekniska sidan har Florian skrivit en omfattande artikel på sin egen webbplats som heter Making docs with MkDocs.
xahteiwi.eu – Making docs with MkDocs
At work, my team and I built and launched a new documentation website, built on Material for MkDocs.
Den officiella lanseringen av dokumentationswebbplatsen ägde rum den 20 februari, då ”beta”-markeringarna togs bort, vilket markerade att plattformen var redo att användas. Denna milstolpe var dock kulmen på månader av hårt arbete. Teamet började med preliminära undersökningar i mitten av 2022 och ökade sina ansträngningar i oktober samma år för att skriva själva innehållet.
Innehållsförteckning
Att välja rätt ramverk och format
Teamets främsta mål var att skapa auktoritativ och tillförlitlig dokumentation för hela Cleura Cloud. De använde Diátaxis-ramverket, en branschstandard, för att vägleda sitt tillvägagångssätt. Ett av de kritiska tidiga besluten var att välja ett dokumentationsformat. I slutändan valde de Markdown tack vare formatets balans mellan uttrycksrikedom och intuitiva användning. Florian förklarade: ”Markdown gör det möjligt att skriva bra dokumentation, men det gör det också möjligt för vem som helst att skriva bra dokumentation utan att behöva sätta sig in i någon knagglig syntax.”
Bild: https://diataxis.fr/
Uppmuntra samarbete genom öppen källkod
Valet av format var viktigt eftersom teamet ville involvera så många bidragsgivare som möjligt. Tekniska skribenter är ofta hårt belastade, och genom att låta utvecklare, konsulter, kvalitetssäkringspersonal och till och med kunder bidra kan Cleura upprätthålla en omfattande dokumentation. Teamet bestämde sig för att lägga upp dokumentationen på GitHub under en Creative Commons-licens, så att vem som helst kan rapportera problem, skicka pull requests och vara säker på att deras bidrag till dokumentationen förblir fria för alla att använda.
Florian förklarar licensens betydelse.
”Om vi uppmuntrar bidrag från Cleura Cloud-användare och kunder måste vi också ge dem en garanti för att deras bidrag alltid kommer att vara tillgängliga helt kostnadsfritt, både för dem och andra.”
Creative Commons Attribution Share-Alike-licensen kräver att alla som använder dokumentationen ska ange ursprungskällan, tillhandahålla en länk och dela med sig av sina ändringar enligt samma villkor.
Implementera verktyg och ett arbetsflöde
När besluten om format och licenser var fattade var teamets nästa utmaning att välja, testa och implementera rätt verktyg för att förverkliga sin vision. Teamet byggde en robust och effektiv plattform för Cleura Cloud-dokumentation med hjälp av Material for MkDocs. Plattformen drivs av ett arbetsflöde där varje ändring genomgår granskning och passerar genom en CI-pipeline innan den skickas till en statisk webbplats. Arbetsflödet innehåller även verktyg för kvalitetskontroll, t.ex. linters, för att upprätthålla en enhetlig dokumentationsstil och kontroller för att undvika döda länkar.
Bild: https://squidfunk.github.io/mkdocs-material/
Linters
Linters är programvaruverktyg som analyserar och kontrollerar källkoden för potentiella problem, t.ex. syntaxfel, inkonsekvenser i formateringen och efterlevnad av kodningsstandarder. När det gäller Cleura Cloud-dokumentation ser linters till att dokumentationsstilen förblir konsekvent mellan olika författare och bidrag. Detta bidrar till att upprätthålla den övergripande kvaliteten och läsbarheten i dokumentationen för våra användare.
https://en.wikipedia.org/wiki/Lint_(software)
Teamet kan effektivisera samarbetet och hantera bidrag genom att lägga upp hela dokumentationsprocessen på GitHub. Genom att använda GitHub Actions kan automatiska kontroller integreras sömlöst och dokumentationswebbplatsen distribueras kontinuerligt. Plattformens utformning underlättar samarbetet och säkerställer att dokumentation av hög kvalitet upprätthålls under hela projektet.
Utnyttja kraften i lagarbete och asynkront samarbete
Även om automatiska kontroller är viktiga för att upprätthålla kvaliteten betonar Florian vikten av mänsklig granskning i dokumentationsprocessen. Teamet förlitar sig på varandra när det gäller återkoppling och revideringar, vilket främjar en god arbetsmiljö där de kan lära sig och växa tillsammans. Den naturliga variationen mellan att skriva och granska andras arbete skapar ett kontinuerligt flöde som ökar produktiviteten.
Efter att ha implementerat verktyg och utformat arbetsflödet är den verkliga utmaningen att samordna de personer som skriver dokumentationen. Ett viktigt bidrag kom från Christos Varelas, en kollega från Grekland, som skrev det mesta av det nya materialet under fyra månader. Arbetsflödet visade sig även vara framgångsrikt när det gällde att locka till sig bidrag från många andra inom företaget. Florian berättade att dokumentationsarkivet för närvarande innehåller 44 000 ord, vilket motsvarar ungefär 100 A4-sidor med enkelt radavstånd.
Utbildningsteamets samarbete är huvudsakligen asynkront, med distansarbete och kommunikation via ärendehanteringssystem, e-post och granskningsprocessen för dokumentation. De håller ett möte per vecka och minimerar användningen av chatt för att undvika avbrott och upprätthålla ett stabilt arbetsflöde. Teamet har framgångsrikt skapat en kultur av ständiga förbättringar, med anställda i hela organisationen som gärna bidrar till dokumentationen utan att bli uppmanade.
Framtidsplaner för docs.cleura.com
I och med den officiella lanseringen av dokumentationsplattformen är teamet långt ifrån färdiga. De fokuserar nu på att utöka bakgrundsdokumentationen, eller ”förklaringarna”, enligt Diátaxis, och stödja den publika betaversionen av Gardener genom att tillhandahålla mer omfattande dokumentation. De arbetar också på en Cleura Cloud Academy-kurs för att hjälpa kollegor och kunder att förstå Gardener bättre. Dessutom har lagringsteamet lämnat in nya handböcker för granskning och publicering. Med dessa pågående insatser fortsätter utbildningsteamet att göra framsteg när det gäller att tillhandahålla värdefulla resurser för alla Cleura-användare.