Ce este documentația software? Tipuri și cele mai bune practici pentru a începe

Dacă doriți ca dezvoltatorii și utilizatorii finali să obțină cât mai multă valoare posibil din software-ul dvs., trebuie să creați documentație software de înaltă calitate.

Dar ce este de fapt documentația software și cum poți să o creezi pentru proiectul tău?

În această postare, vom explora tot ce trebuie să știți despre documentația software, inclusiv următoarele:

• Ce este documentația software?
• Diferitele tipuri de documentație software (cu exemple)
• Cum să vă publicați documentația software (cele mai bune instrumente)
• Câteva bune practici pentru crearea documentației software de calitate

Să pătrundem!

Ce este documentația software?

Documentația software este conținut care ajută utilizatorii finali, dezvoltatorii și/sau angajații dvs. să înțeleagă software-ul dvs. și să-l folosească pentru a-și îndeplini obiectivele în mod eficient.

De obicei, veți publica documentația software-ului pe site-ul dvs. web. Oamenii îl pot accesa apoi pentru a afla mai multe despre software-ul dvs. și cum funcționează.

În această definiție largă a documentației software, există diferite tipuri de documentație software. Să discutăm asta în continuare.

Diferitele tipuri de documentație software

Puteți împărți aproximativ diferitele tipuri de documentație software în câteva categorii mari.

Primul aspect este pentru ce tip de persoană este destinată documentația:

• Documentația utilizatorului – aceasta este documentația pe care ați creat-o pentru utilizatorul final al produsului. Îi ajută să înțeleagă cum să folosească software-ul dvs. din perspectiva unui utilizator obișnuit, care poate avea sau nu cunoștințe tehnice speciale.
• Documentația pentru dezvoltatori – aceasta este documentația software mai tehnică pe care ați creat-o pentru dezvoltatori, cum ar fi documentația API.

Al doilea aspect este dacă documentația este destinată publicului extern sau intern:

• Documentație software externă – aceasta este documentație publică pe care ați creat-o pentru a vă ajuta utilizatorii.
• Documentația internă a software-ului – aceasta este documentația privată pe care ați creat-o pentru angajații dvs. pentru a-i ajuta să lucreze mai eficient și să înțeleagă detaliile cheie.

De exemplu, este posibil să aveți un set de documentație pentru dezvoltatori pentru echipele dvs. interne, care să vă ajute să lucrați la software și un alt set de documentație pentru dezvoltatori destinate publicului pentru dezvoltatorii externi.

Să descompunem aceste tipuri de documentație software mai detaliat...

Exemple de documentație software pentru documentația pentru dezvoltatori

• Documentația API – arată dezvoltatorilor cum să interacționeze cu API-ul software-ului tău.
• Citiți -mă – prezentați-vă software-ul și explicați ce face – de obicei, primul lucru pe care oamenii îl citesc.
• Note de lansare – documentați noile versiuni ale software-ului dvs., inclusiv orice modificări importante.
• Documentație de arhitectură – arată structura software-ului dvs., incluzând eventual diagrame.
• Documentația modelului de date – documentați diferitele structuri de date din software-ul dvs., inclusiv relațiile dintre diferitele structuri de date.
• Documentația procesului – documentați procesele cheie, cum ar fi rapoartele de erori, foile de parcurs, asigurarea calității, protocoalele de testare și așa mai departe.

Pentru un exemplu real de documentație software de documente axate pe dezvoltatori, puteți consulta documentația „Dezvoltatori” a Gravity Forms, care acoperă diverse subiecte, cum ar fi:

• Cârlige PHP (pentru WordPress)
• Obiecte de date
• API PHP
• Bază de date
• API-ul REST

De exemplu, iată cum arată documentația REST API:

Exemple de documentație software pentru documentația utilizatorului

• Ghid introductiv – arată utilizatorilor cum să pornească rapid și să ruleze software-ul.
• Tutoriale pentru cazuri de utilizare specifice – tutoriale mai specifice pentru realizarea unor sarcini specifice.
• Glosare de termeni/manuale de referință – ajută utilizatorii să înțeleagă termenii și detaliile cheie.
• Întrebări frecvente – răspunde la întrebările frecvente.

Pentru un exemplu real despre cum ar putea arăta documentația software mai concentrată pe utilizator, puteți apela la același exemplu Gravity Forms de mai sus.

Dacă te uiți la articolele Gravity Forms mai concentrate pe utilizator, vei vedea o mulțime de tutoriale pas cu pas despre cum să realizezi sarcini folosind interfața software, împreună cu glosare și explicații ale caracteristicilor cheie.

În comparație cu documentația software-ului pentru dezvoltatori, veți vedea mai multe capturi de ecran și explicații în limbaj simplu și mult mai puține blocuri de cod.

Cum se publică documentația software: Trei cele mai bune instrumente de documentare software

Pentru a publica documentația software-ului pe site-ul dvs., veți dori un instrument dedicat de documentare software sau un anumit tip de sistem de management al cunoștințelor.

În această secțiune, vom acoperi rapid unele dintre cele mai bune instrumente de documentare software. Apoi, în secțiunea următoare, vom trece peste câteva dintre cele mai bune practici pentru crearea documentației de calitate.

Dacă doriți o privire mai aprofundată aici, poate doriți să citiți ghidurile noastre complete despre cele mai bune instrumente de documentare și cel mai bun software de documentare tehnică.

Baza de cunoștințe eroică

Heroic Knowledge Base este un plugin de documentare și bază de cunoștințe pentru popularul software WordPress open-source.

Cu Heroic Knowledge Base, vă puteți găzdui documentația și puteți menține controlul deplin, accesând în același timp toate funcțiile de care aveți nevoie pentru a crea documentație software eficientă.

Iată câteva dintre caracteristicile de bază pe care le obțineți cu Heroic Knowledge Base:

• Editor de conținut flexibil , inclusiv blocuri încorporate pentru înștiințări și alte detalii importante de stil.
• Cuprins automat, astfel încât utilizatorii să poată vedea rapid ce conținut este acoperit într-un articol de documentare și să sară la anumite secțiuni.
• Controlul reviziilor și istoricul versiunilor prin sistemul nativ de revizuire WordPress.
• Funcții de descoperire de conținut, inclusiv căutare Ajax în timp real cu sugestii live, categorii și multe altele.
• Sistem de feedback al utilizatorilor care le permite oamenilor să evalueze articolele ca fiind utile sau neutile și să împărtășească feedback.
• Analize de căutare, astfel încât să puteți vedea ce caută utilizatorii, precum și orice termeni de căutare care nu returnează rezultate.
• Widget cu răspunsuri instantanee pentru a permite utilizatorilor să caute și să acceseze documentația software de oriunde pe site-ul dvs.

Deoarece Heroic Knowledge Base și WordPress sunt atât auto-găzduite, cât și open-source, sunteți, de asemenea, liber să vă modificați configurația după cum este necesar.

Puteți să îl faceți public sau să restricționați accesul la documentația dvs. cu diverse tactici, cum ar fi parole, conturi de utilizator, adrese IP, un intranet și multe altele.

Baza de cunoștințe eroică începe de la doar 149 USD pe an.

Citiți documentele

Citiți documentele este un instrument de documentare care se concentrează pe a vă ajuta să creați documentația pentru dezvoltatori.

Dacă vă concentrați în mod special pe crearea documentației tehnice pentru dezvoltatori, poate fi o altă opțiune bună de luat în considerare.

Puteți să vă gestionați conținutul și istoricul revizuirilor folosind Git și apoi să vă implementați documentele într-o interfață frontend.

Iată câteva dintre celelalte caracteristici notabile din Citiți documentele:

• Analize încorporate pentru a vedea ce citesc și caută utilizatorii dvs.
• Acceptă mai multe versiuni simultane , ceea ce poate fi util dacă oferiți mai multe versiuni ale software-ului dumneavoastră – de exemplu, un set de documentație pentru versiunea 1.0 și altul pentru versiunea 2.0.
• Exportați documentația în diferite formate, inclusiv PDF, HTML și epub.
• Sugestii de căutare live pentru a ajuta utilizatorii să găsească documente.

Citiți documentele este gratuit pentru utilizare dacă aveți un proiect de software open-source.

Pentru produsele software comerciale, există un serviciu plătit Read the Docs for Business, care începe de la 50 USD pe lună.

GitBook

GitBook este un alt instrument tehnic de documentare software care vă permite să vă gestionați documentația folosind Git, cu suport atât pentru depozitele GitHub, cât și pentru GitLab.

Sau, dacă nu doriți să utilizați Git, GitBook vă permite, de asemenea, să vă creați documentația folosind un editor de text sau să o importați din fișiere markdown sau .doc.

Iată câteva alte caracteristici notabile pe care le oferă GitBook:

• Controlul versiunilor pentru a urmări revizuirile și istoricul versiunilor.
• Editarea live în echipă , care este utilă dacă aveți nevoie de mai mulți autori care să colaboreze la articole.
• Organizați articole folosind „spații” și „colecții” – fiecare spațiu poate avea mai multe colecții în interiorul său.
• Opțiune de export PDF , astfel încât utilizatorii să vă poată exporta cu ușurință documentația ca descărcare PDF.

GitBook este gratuit pentru proiecte non-profit sau open-source.

Pentru proiectele software comerciale, GitBook începe de la 8 USD pe utilizator pe lună, cu un minim de 5 utilizatori. Asta înseamnă că cel mai ieftin tarif lunar este de 40 USD pe lună.

Cele mai bune practici pentru crearea documentației software

Pentru a finaliza lucrurile, haideți să cercetăm câteva dintre cele mai bune practici pentru documentația software pentru a vă ajuta să creați o documentație eficientă.

Gândiți-vă la obiectivele și nevoile utilizatorilor

Când scrieți un articol de documentație software, este important să începeți prin a răspunde la câteva întrebări de bază:

• Cine este utilizatorul pentru care scrii?
• Ce încearcă să realizeze utilizatorul?
• Ce nivel de cunoștințe tehnice are utilizatorul?

Cunoașterea răspunsurilor la aceste întrebări vă va ajuta să înțelegeți ce conținut să acoperiți și cum să structurați articolul în cel mai optim mod.

De exemplu, să presupunem că oferiți un software de programare a rețelelor sociale și scrieți un articol care îi ajută pe managerii rețelelor sociale să își programeze prima postare pe rețelele sociale.

Când scrieți documentația software-ului, ați dori să vă concentrați pe afișarea modului cel mai simplu pentru un utilizator final obișnuit de a îndeplini acest obiectiv.

Dacă oferiți și un API pentru a permite dezvoltatorilor să-și configureze propriile integrări, probabil că ați dori să acoperiți asta într-un alt articol ( deși ați putea menționa și trimiteți la acea metodă ).

Includeți documentația software în procesul de dezvoltare

Când creați documentație software, este ușor să cădeți în capcana așteptării până când un proiect este finalizat pentru a-l documenta.

Cu toate acestea, acest lucru poate duce rapid la datorii de documentare, deoarece este posibil să expediați noi funcții sau modificări înainte ca acestea să fie documentate.

Pentru a evita acest lucru, faceți din documentația software o parte conștientă a ciclului de dezvoltare a software-ului. Dacă o caracteristică sau un produs nou nu a fost încă documentat, nu este gata de livrare chiar dacă codul în sine este terminat.

Făcând din documentație o cerință de bază a procesului de dezvoltare software, vă puteți asigura că tot ceea ce trimiteți este însoțit de documentația adecvată.

Utilizați formatare și stil consecvent

Pentru a ajuta oamenii să lucreze mai eficient cu documentația dvs. software, este important să utilizați formatare și stil consecvent în toată documentația dvs.

Utilizarea aceleiași formatări le permite cititorilor să învețe cum este structurată documentația dvs. software, ceea ce le va facilita accesul rapid la informațiile de care au nevoie.

Pentru a ajuta la obținerea acestei coerențe, este posibil să doriți să creați un ghid de stil dedicat documentației software.

Instrumentul dvs. de gestionare a documentației software ar putea include, de asemenea, funcții care să vă ajute să obțineți un stil consistent.

De exemplu, pluginul Heroic Knowledge Base include înștiințări pre-stilizate pentru a evidenția informațiile cheie sau avertismentele. Folosind acestea, puteți asigura o formatare consecventă în întreaga documentație.

Folosiți experți pentru a scrie documentație tehnică

Pentru documentația software orientată către utilizator, este posibil să nu aveți nevoie de experți în domeniu pentru a scrie conținutul.

Cu toate acestea, pentru documentația software mai tehnică, cum ar fi documentația API axată pe dezvoltatori, probabil că veți dori să desemnați pe cineva cu cunoștințele tehnice relevante pentru a scrie acele documente.

Acesta ar putea fi un scriitor tehnic dedicat, cu expertiză în domeniu, dacă organizația dvs. are resursele necesare pentru a angaja pentru acea poziție. Sau, ar putea fi unul dintre dezvoltatorii dvs.

Important este că scriitorul înțelege aspectele tehnice ale software-ului dvs. la un nivel suficient de profund pentru a le explica altor utilizatori tehnici.

Faceți mai ușor pentru oameni să descopere conținut (căutare/filtru)

Pe măsură ce biblioteca dvs. de documentație crește, va deveni mai dificil pentru utilizatori să găsească articolele de documentare care se adresează nevoilor lor.

Pentru a încerca să evitați această problemă, veți dori să vă concentrați pe îmbunătățirea posibilității de descoperire a documentației software.

O primă strategie este să vă împărțiți documentația după tip.

De exemplu, de obicei, veți dori să separați documentația pentru utilizatorul final de documentația software-ului pentru dezvoltatori.

În cadrul acesteia, puteți folosi și categorii pentru a împărți articolele. Puteți utiliza categorii bazate pe caracteristici, cazuri de utilizare, suplimente și așa mai departe - orice are sens logic pentru produsul dvs. software.

În conformitate cu același exemplu Gravity Forms de mai sus, puteți vedea că Gravity Forms împarte documentația pentru utilizatorul final pe tipuri de caracteristici.

O altă caracteristică utilă de descoperire este sugestiile de căutare live. Utilizatorii pot începe să tasteze o interogare relevantă în caseta de căutare și să vadă instantaneu articole de documentație care se potrivesc cu acea interogare.

Multe instrumente de documentare includ funcționalitate încorporată de căutare live, inclusiv baza de cunoștințe eroică.

Păstrați documentația software-ului actualizată

Deoarece software-ul dvs. se schimbă mereu, documentația dvs. de software va fi întotdeauna o lucrare în curs.

Pe măsură ce lucrurile se schimbă în software-ul dvs., va trebui să vă actualizați prompt documentația pentru a reflecta aceste modificări.

În caz contrar, documentația dvs. nu va fi doar „nu este de ajutor”, dar ar putea crea confuzie în rândul utilizatorilor dvs.

Pentru a vă asigura că aceste actualizări au loc, veți dori să atribuiți anumite persoane să dețină documentația și procesul de actualizare. În acest fel, nu există nicio ambiguitate cu privire la cine este responsabil pentru menținerea exactă a tuturor lucrurilor.

Utilizați feedbackul clienților pentru a vă îmbunătăți documentația

Pe lângă faptul că aveți propria echipă care lucrează la revizuirea și actualizarea documentației software, veți dori, de asemenea, să luați în considerare feedback-ul clienților.

Clienții pot oferi informații valoroase despre cât de util (sau potențial inutil) este un anumit articol de documentație software, împreună cu detalii despre cum îl puteți îmbunătăți.

Pentru a automatiza procesul de feedback al clienților, veți dori să căutați un instrument de gestionare a documentației care să includă funcții încorporate pentru feedbackul clienților.

De exemplu, pluginul Heroic Knowledge Base permite utilizatorilor să evalueze un articol ca fiind util sau inutil și, de asemenea, să ofere opțional feedback în formă liberă.

Puteți vizualiza apoi toate aceste informații din tabloul de bord pentru a identifica rapid articolele de documentație pe care trebuie să le îmbunătățiți.

Începeți să vă documentați software-ul astăzi

Documentația software vă ajută pe dvs. și clienții dvs. să lucrați mai eficient și să obțineți mai multă valoare din software-ul dvs.

Există diferite tipuri de documentație software, așa că veți dori să vă gândiți ce tipuri se potrivesc nevoilor proiectului dvs. software.

Este posibil să aveți documentație diferită pentru echipele interne sau externe, precum și pentru diferite tipuri de clienți, cum ar fi dezvoltatori vs utilizatori finali.

Pentru a crea o documentație eficientă, veți dori să urmați cele mai bune practici din această postare.

Pentru a publica acea documentație, puteți utiliza un instrument open-source precum Heroic Knowledge Base, care se bazează pe puternicul software WordPress.

Veți obține flexibilitatea și proprietatea unei platforme auto-găzduite, cu toate caracteristicile și funcționalitățile de care aveți nevoie pentru a publica documentație software de înaltă calitate.

Dacă doriți să aflați mai multe, faceți clic aici pentru a accesa Baza de cunoștințe eroică.