Skriva dokumentation för ditt WordPress Theme Framework

Så, du har nu ett WordPress-tema ramverk. grattis! Det svåra arbetet du har tagit för att utveckla det kommer att löna sig i längden och göra din utvecklingsprocess mjukare, mer strömlinjeformad och effektivare.

Men du måste göra en sista sak innan du är klar, och det är att dokumentera din ram. Åtminstone måste du se till att en bra kommentar används i hela koden, men det är också användbart att skriva en annan dokumentation så att du kan hålla reda på filerna, funktionerna och filtren som utgör ramverkets API.

Alternativen jag täcker är:

  • kommentar
  • Skapa en readme-fil
  • Använda automatiserade dokumentationsverktyg
  • Skapa en wiki
  • Skapa en webbplats
  • Skapa handledning eller spela in videoklipp

Observera att medan jag kommer att nämna några dokumentationsverktyg, fungerar inte denna handledning som en rekommendation eftersom jag inte har använt dem för min egen ram, så du måste själv bestämma om deras lämplighet.

Skriva kvalitetskommentarer

Kommentarer är särskilt viktiga när andra utvecklare kommer att arbeta med din kod (till exempel om du är del av ett lag eller om du släpper ut din ram). Men de är också ovärderliga om du jobbar på egen hand, eftersom det är väldigt enkelt att glömma exakt vad en bit kod gör när du kommer att redigera det ett år eller längre nerför linjen.

Tänk dig att du har använt ditt ramverk för att bygga upp en kundwebbplats. Två år från nu utvecklar området ett problem klockan 5:30 på fredag ​​eftermiddag. Goda kommentarer kan göra skillnaden mellan att lösa problemen snabbt och vara hemma för helgen, mot att sloga igenom hundratals linjer kod och saknar din fredagskväll ut.

Här är några tips för bra kommentarer:

  • Använd kommentarer i början av filen för att förklara vad filen gör. Exempelvis innehåller i mallfiler en anteckning om vilka data den visar och eventuella anpassningar du har gjort till loopen eller andra delar av filen. och i plugin-filer lägger du till en anteckning om dess funktionalitet. Till exempel. kommentaren nedan berättar användarna namnet på mallfilen, vad det gör, temat det är en del av (@paket), och vilken version av temat den har varit på plats sedan (@eftersom). Du bör använda ett liknande system för pluginfiler.
/ ** * Mallnamn: sidebar-products.php * * Inkludera filen som används för sidofältet på sidor med hjälp av single-product.php-mallen. Visar ett galleri av produktbilder (utelämnande av den utvalda bilden som visas i innehållet). * * @package wpptl-theme-framework * @since version 1.0 * /
  • Använd kommentarer för att avgränsa delarna av din kod, inte bara i stylesheets men också i tematmallfilerna och funktionsfilen.
  • Kommentera något som är nonstandard.
  • Kommentera något som tog dig tid att träna - använd detaljerade kommentarer så när du kommer tillbaka till det behöver du inte tänka igenom det igen.
  • Kommentera allt som du vet att någon annan kommer att arbeta med, till exempel om dina temafiler innehåller skript som du kommer att be en annan utvecklare att göra perfekt, lägg till kommentarer som förklarar var de gäller på webbplatsen.
  • Använd formulering i dina kommentarer som du kan hitta med hjälp av en sökning senare - så förkorta inte och använd termer som andra skulle förstå.
  • När du kommenterar någon kod, lägg till en kommentar till dig själv med anledningen. På det sättet, om du glömde att ta bort koden när du är klar, eller vill lägga till den i framtiden, vet du vad som händer.
  • När du är osäker, lägg till en kommentar!

Skapa en readme-fil

en readme.txt filen är nästa nivå upp efter att kommentera. Det är en enda fil som du inkluderar i ditt tema och innehåller information om temat.

Kodbunten som följer med denna serie innehåller en enkel readme.txt fil:

Skapa ditt eget WordPress-temarama Detta tema stöder den 6: e delen av denna serie för wptutsplus. Temat innehåller följande mallfiler: archive.php index.php page.php - för statiska sidor sida-full-width.php archive.php - för arkivsidor header.php sidebar.php footer.php loop.php loop-single .php loop-page.php functions.php Temat stöder utvalda bilder, menyer och widgets och använder dem enligt följande: Utvalda bilder: Dessa visas i arkiv- och indexmallarna om de är närvarande, med medelstorleken. Menyer: Standardmenyn finns i header.php, och använder menysadministratör Styling Temat använder Object Oriented CSS (OOCSS). Följande klasser är för layout och du kan använda dem i dina sidor och inlägg. De är lyhörda, så de kommer att ändra storlek på mindre skärmar (till exempel .half-klassen är full bredd på telefoner) .full bredd. Tre kvartdelar. Två tredjedelar. Halvedelskvartal. Hakar Det finns 7 actionhakar: ovanför rubrik Inne i rubriken Innan innehållet Efter innehållet i sidofältet I sidfoten Efter fotfoten Det finns tre filterhakar: 1 i rubriken 2 i fotfoten Widget-områden Det finns sex widgetområden, alla adderade via widgets.php-filen: - en i rubriken - en i sidofältet - fyra i sidfoten

Om du vill göra din readme filen mer användarvänlig, kanske du vill överväga att skapa en readme.html filen istället som öppnas i en användares webbläsare. Du kan använda CSS för att märka din readme fil och gör det lättare att läsa.

Om du vill släppa ditt tema till allmänheten via WordPress-temförvaret, förväntas du ge en readme.txt filen som en minsta form av dokumentation. Jag kommer att fördjupa det här i mer detalj i den slutliga handledningen i den här serien om att släppa ut tematramverket.

Använda automatiska dokumentationsverktyg

Om du planerar att fortsätta att utveckla din ram och inte vill lägga mycket tid manuellt med att skriva dokumentation för varje ny funktion, kan ett automatiskt dokumentationsverktyg vara svaret.

De flesta av dessa innebär att du använder specifika taggar eller syntax för att göra det möjligt för systemet att identifiera var du ska skapa dokumentation. Exempel är:

  • PHPDocumentor som är PHP-specifik
  • APIgen också PHP specifikt
  • doxygen
  • Groc

Om du ska använda ett av dessa verktyg är det värt att spendera lite tid att identifiera det bästa för dig innan du börjar, eftersom du inte kommer att kunna överföra dokumentationen från en till en annan. 

Men när du har tagit tag i systemet och fått det upprättat kan ett automatiskt verktyg som dessa spara mycket tid och du kan undvika luckor i dokumentationen längs linjen, eftersom du kommer vara så upptagen med att skriva kod du har inte tid att uppdatera dina dokument.

Skapa en Wiki eller Webbplats

Det här alternativet kommer att vara mer arbete och det är bara värt att göra om du ser din ram växa över tiden och få en betydande användarbas. Alla de stora tematiska ramarna har egna webbplatser med dokumentation, som antingen är fritt tillgängliga eller endast tillgängliga för medlemmarna.

Webbplatsen för att stödja dina ramar kan vara en del av din intäktsstrategi - temat ramverket är till exempel gratis, men dokumentationen och supporten på den medföljande webbplatsen är endast tillgänglig för betalande abonnenter.

Alternativt om du släpper dina ramar som en premiumprodukt, kan du kräva att abonnenter loggar in på docsna, eller du kan välja att göra din dokumentation offentlig i hopp om att det kommer att uppmuntra fler människor att köpa.

Om din ram är helt fri kan du välja att skapa en gratis hemsida med dokumentation, vilket är fallet med Wonderflux-ramverket:

Alternativt kan du bestämma dig för att skapa en wiki, vilket har fördelen att låta dina användare bidra till dokumenten. Detta kommer att ta mer tid att installera än en webbplats i de flesta fall, men kan vara ett värdefullt verktyg för samhället som använder din ram. Du kan skapa en wiki med ett plugin för din rams WordPress-webbplats.

Skapa handledning eller spela in videoklipp

Tutorials kan hjälpa nya användare, särskilt de som inte kan skriva kod, få tag på dina ramar snabbare än standarddokumentationen. Videor tar detta ett steg längre, vilket ger en lättanvänd visuell guide och ett bra marknadsföringsverktyg.

Genesis-ramen har en rad handledningar för användare som endast är tillgängliga för betalda abonnenter:

Mitt eget Edupress-ramverk har ett antal handledningsvideor som jag skapade för att hjälpa användare med en varierande grad av datorupplevelse och lite erfarenhet av att använda WordPress:

Dessa visas på den offentliga webbplatsen och även i användarnas instrumentpaneler, så att de enkelt kan komma åt dem när de arbetar med ramverket. Om du skapar dokumentation, handledning eller videor för din ram kan du inkludera en skärm i instrumentbrädan med information om dina dokument.

Att skapa handledningar eller videor är dock mycket tidskrävande och behöver mycket arbete för att få rätt: dåligt skrivna handledning eller dåligt producerade videor kommer att reflektera dåligt på dina ramar och kan göra dig mer skada än en enklare form av dokumentation. 

Sammanfattning

Vem som helst kommer att använda ditt temamaterial, är en form av dokumentation väsentlig. Oavsett om du just utvecklar ramen för dig och ditt team eller släpper det för större användning, måste du spela in information om filstrukturen och API: n.

De alternativ som jag har diskuterat ovan varierar från de enkla kommentarerna till de mer komplexa videon, med allt däremellan. Vad du bestämmer dig för, kommer att bero på dina användares behov och kan komma att förändras över tiden eftersom du får en större användarbas.