18 instrumente de documentare software care fac munca grea pentru tine

🟢 Material bonus: Lista de verificare a fluxului de lucru Git pentru a simplifica & eficientiza gestionarea versiunilor

Fără documentație, software-ul este doar o cutie neagră. Iar cutiile negre nu sunt nici pe departe atât de utile pe cât ar putea fi, deoarece funcționarea lor interioară este ascunsă de cei care au nevoie de ele în aer liber.

Documentația software-ului vă transformă software-ul într-o cutie de sticlă, explicându-le utilizatorilor și dezvoltatorilor cum funcționează sau cum este utilizat.

Probabil că ați mai văzut documentația înainte, dar dacă aveți nevoie de o reîmprospătare, iată un exemplu din API-ul Slack:

După cum puteți vedea, Slack explică totul despre API-ul său în detalii extenuante. Orice pagină conexă este legată, există o bară laterală cu subiecte ușor de accesat și capturi de ecran cu ceea ce utilizatorul se poate aștepta să vadă.

Pentru a explica acest lucru mai în detaliu, vom aborda următoarele subiecte în acest post de pe Process Street:

• Ce este documentația software?
• Opțiuni de găzduire a documentației software
• Instrumente de scriere pentru documentația software
• Cuvinte finale despre documentația software

Să începem.

Ce este documentația software?

„Documentația în ingineria software este termenul general care cuprinde toate documentele și materialele scrise care se referă la dezvoltarea și utilizarea unui produs software.” – Prototype.io, Software Documentation Types and Best Practices

Toate piesele de software ar trebui să aibă o formă de documentație care să explice, în detaliu, ce este produsul, cum funcționează și de ce funcționează în acest fel.

„Dacă nu este documentat, nu există” – Sitepoint, A Guide to Writing Your First Software Documentation

În calitate de dezvoltator, principalul dvs. obiectiv este să scrieți cel mai bun cod posibil. Vrei ca codul tău să fie cel mai bun din clasă, ușor de citit, ușor de folosit și vrei ca în urma lui să se întâmple lucruri grozave. Nu-i așa?

Dar fără să documentați ce ați făcut și de ce ați făcut-o:

• Nimeni altcineva nu vă poate folosi codul în afară de dumneavoastră

Fără documentație, nimeni nu va înțelege ce ați făcut și de ce ați făcut-o. Va fi incredibil de dificil, aproape imposibil, ca altcineva să preia codul tău și să lucreze la el. S-ar putea chiar să renunțe la el și să o ia de la capăt, deoarece, în unele cazuri, acest lucru ar fi mai rapid decât să încerce să înțeleagă ce ați făcut și de ce.

• Nu îl poți actualiza sau îmbunătăți

Îți poți aminti ce ai mâncat la cină sâmbătă, cu trei luni în urmă? Cu excepția cazului în care sunteți o creatură completă a obișnuinței, sunt șanse să nu puteți. Așa că este corect să spunem că probabil nu vă veți aminti codul pe care l-ați scris, la două, trei, patru luni după ce l-ați făcut. Dacă nu vă puteți aminti motivele care au stat la baza deciziilor dumneavoastră de codare, atunci vă veți strădui să reușiți să îl actualizați sau să îl îmbunătățiți.

În ciuda acestui fapt, documentarea software este adesea o sarcină care este grăbită, făcută prost, deprioritizată sau uitată cu totul.

Înainte de a începe să vorbim despre ce instrumente puteți folosi pentru a scrie documentația software, trebuie să ne gândim la o modalitate de a ne asigura că sarcina este îndeplinită în primul rând.

Aici este locul în care Process Street vă poate ajuta.

Process Street este o bucată de software de gestionare a proceselor de afaceri (BPM) care poate fi folosit pentru a crea, gestiona și urmări procesele.

Mai multe despre ce este Process Street mai târziu, deocamdată, permiteți-mi să vă arăt cum îl puteți folosi ca un instrument care să vă ajute să integrați documentația software în fiecare proiect de dezvoltare software la care lucrați.

Mai jos este un exemplu de șablon pre-fabricat al procesului de implementare software. Acest șablon a fost creat pentru a ajuta inginerii de software și programatorii să își implementeze software-ul în cel mai bun mod posibil.

Click aici pentru a accesa Procesul de implementare a software-ului!

Pentru a obține acest șablon, fie vă conectați și îl adăugați la tabloul de bord, fie vă înregistrați pentru o perioadă de probă gratuită.

Acest șablon este un exemplu perfect de proces pe care îl puteți urma de fiecare dată când doriți să implementați o bucată nouă sau actualizată de cod.

Acesta are pași clari care vă vor ghida prin întregul proces de implementare, de la configurarea unui mediu de pregătire până la punerea în funcțiune a modificărilor. Acești pași se vor asigura că nimic nu este omis și că întregul proces decurge fără probleme de fiecare dată.

Am conceput acest șablon pentru a fi folosit ca un ghid pentru a vă ajuta să creați un proces de implementare care să funcționeze pentru dumneavoastră. Fiecare companie este diferită, fiecare proiect software este diferit și fiecare proces de implementare este diferit.

Puteți edita acest proces și adăugați sarcinile care sunt relevante pentru dumneavoastră, compania dumneavoastră și proiectul dumneavoastră.

Ceea ce mă aduce înapoi la documentația software; ați putea adăuga „documentația software” ca sarcină. În acest fel, oricine lucrează prin procesul de implementare a software-ului va fi reamintit și încurajat să completeze acest lucru, ca parte a procesului.

Am mai multe șabloane de procese prefabricate care v-ar putea fi de folos, pe care le voi include la sfârșitul acestei postări.

Înainte de a ajunge la asta, haideți să ne uităm unde puteți stoca documentația software.

Opțiuni de găzduire a documentației software

Nu este bine să ai doar o grămadă de fișiere text care să trăiască pe computerul tău. Ele trebuie să fie accesibile dezvoltatorilor și utilizatorilor, ceea ce cel mai probabil veți face prin găzduirea documentației pe internet, deoarece nu este vorba de anii 1980.

Process Street (pentru uz intern)

Pentru instruirea noilor dezvoltatori și pentru a vă păstra documentația vie, toate în același loc, Process Street este o alegere solidă pentru documentația software.

În primul rând, ați putea crea un proces de scriere a documentației dvs. pentru a vă asigura că surprindeți toate detaliile corecte și că o faceți cât mai utilă posibil.

Utilizând următoarele caracteristici ușor de utilizat, puteți apoi să vă redactați și să vă stocați documentația într-un singur loc:

• Widget-uri de imagine
• Widget-uri de text
• Widget-uri video
• Widget-uri de fișiere
• Subiecte
• Widget-uri de e-mail
• Widget-uri de embed

Stocarea documentației dvs. în Process Street înseamnă că poate fi accesată de toată lumea din companie. Puteți să o partajați cu alții, să o trimiteți spre aprobare, să setați memento-uri pentru a o revizui și să o actualizați cu ușurință.

Verificați:

Dacă poate fi documentat, poate fi documentat în Process Street.

Înscrieți-vă pentru o perioadă de probă gratuită aici și încercați-l.

Read The Docs

Este remarcabil faptul că Read The Docs este gratuit când vezi tot ceea ce poate face. Similar cu GitHub, puteți crea oricât de mult material open-source doriți, care este indexat în mod deschis pe site, dar vă va costa dacă doriți ca documentele să fie private și interne pentru compania dumneavoastră. Pentru scopurile noastre, este probabil că veți fi în regulă cu faptul că documentația va fi ușor disponibilă pentru utilizatori pe web.

Motivul pentru care Read The Docs este atât de bun este că puteți importa fără efort documentația din orice sistem de control al versiunilor, inclusiv Git, Mercurial, Subversion și Bazaar. De asemenea, suportă webhooks, astfel încât documentația să fie construită automat ori de câte ori trimiteți codul.

Consultați ghidul lor Getting Started pentru a vă face o idee despre cum funcționează și cum s-ar comporta documentația dvs. atunci când este găzduită acolo.

GitHub (& GitHub Pages)

Dacă folosiți GitHub pentru a gestiona controlul versiunilor pentru software-ul dvs., aveți, cel puțin, un fișier README.MD în depozit. Pentru a utiliza GitHub pentru a vă documenta software-ul, așa cum au făcut milioane de alte persoane în trecut, completați acel README cu markdown.

Un exemplu excelent este depozitul t al lui sferik, capturat aici:

Dacă doriți mai mult decât o singură foaie de text formatat, puteți profita de instrumentul Pages de la GitHub (primiți o pagină web gratuită + găzduire cu fiecare cont GitHub, și puteți chiar să direcționați un domeniu personalizat către aceasta). Pages are chiar și teme implicite foarte arătoase, care fac ca documentația dvs. să aibă un aspect profesional.

Acesta este documentația atom.io pentru Electron găzduită pe GitHub. Este o alegere inteligentă, deoarece funcționează automat cu controlul versiunilor de pe GitHub, la fel ca și restul software-ului dumneavoastră. Vedeți depozitul site-ului aici.

Dropbox Paper (pentru uz intern)

Pentru utilizarea internă a documentației software, Dropbox Paper este o alegere excelentă. Ca și predecesorul său Hackpad, îl puteți folosi pentru a crea un wiki privat pentru angajați. Puteți să legați documente între ele, să inserați blocuri de cod, imagini și salturi de pagină, așa cum ați cere de la orice instrument de documentare.

După cum puteți vedea din comentariile din dreapta, îl puteți folosi și pentru a trece prin procese de aprobare și pentru a colabora asupra creării documentației. În general, este un instrument excelent pentru dezvoltarea și crearea de documentație la nivel intern, poate cu scopul de a o face publică mai târziu, sau pur și simplu să o păstrați pentru uz intern.

Atlassian REST API Browser (pentru utilizarea API)

Atlassian’s REST API Browser (RAB) este inclus în instanțele JIRA Server, Confluence Server și Stash în mod implicit. Este construit pentru a descoperi API-urile disponibile pentru utilizare în mediile JIRA/Confluence și, de asemenea, un loc pentru a vă găzdui documentația. Dacă, bineînțeles, API-ul dvs. se potrivește.

Documentați-vă API-ul folosind acest instrument pentru a oferi API-ului dvs. compatibil cu JIRA/Confluence mai multă expunere. Consultați aici documentația Atlassian pentru a face acest lucru.

Tettra (pentru uz intern)

Tettra este un fel de software de bază de cunoștințe unde vă puteți documenta dezvoltarea, sau orice altceva.

Utilizăm Tettra intern la Process Street pentru o mulțime de cazuri de utilizare. Zi de zi, folosesc Tettra pentru a avea un singur loc unde sunt documentate toate procesele mele, astfel încât să nu uit niciodată cum se leagă unul de altul sau cum au fost configurate diferitele automatizări pe care le-am construit.

Tettra este grozav dacă doriți să creați un fel de bibliotecă. Acest lucru înseamnă că este genial pentru documentația software sau chiar și doar ca un wiki intern pentru compania dumneavoastră.

Din moment ce Tettra este conceput în mod special pentru managementul cunoștințelor, vine și cu o serie de alte caracteristici de sprijin. De exemplu, poate face sugestii cu privire la conținutul sau secțiunile suplimentare pe care ați putea dori să le adăugați pentru a oferi o imagine mai completă a organizației dvs. și a modului în care lucrurile se potrivesc între ele.

Puteți vedea un mic videoclip aici pentru modul în care o echipă de dezvoltare ar putea căuta să utilizeze Tettra: How Product & Engineering Teams Use Tettra.

Sau puteți merge aici pentru a citi despre cum folosim Tettra alături de Process Street: Automatizarea fluxurilor de lucru și a listelor de verificare: Process Street Case Study.

Veziți!

Apiary (pentru utilizarea API)

Pe lângă faptul că este un loc în care trăiesc albinele, Apiary este o gazdă dedicată pentru documentația API. Scrieți în markdown, adăugați apeluri API simulate, iar Apiary adună toate acestea în ceva asemănător cu ceea ce vedeți mai jos:

Oricine poate testa API-ul fără a fi nevoit să intre în aplicație sau să programeze efectiv un apel, ceea ce îl face o modalitate super accesibilă de a vă împărtăși API-ul, de a-l documenta în profunzime și de a vă lăuda cu ceea ce poate face.

Am discutat unde să stocați documentația software-ului dumneavoastră, acum este timpul să ne uităm la cum să o scrieți.

Instrumente de scriere pentru documentația software

Documentația software este adesea scrisă în markdown pentru a permite hyperlink-uri și formatare, păstrând în același timp textul simplu, astfel încât să poată trăi alături de fișierele de cod în controlul versiunilor. Acest lucru înseamnă că multe dintre alegerile mele pentru instrumente de scriere sunt editoare simple de markdown care fac experiența de scriere plăcută. În plus, există, de asemenea, câteva soluții non-mparkdown foarte eficiente aruncate acolo.

MarkdownPad (Windows)

Cu o versiune gratuită și una premium – ambele cu o mulțime de caracteristici excelente – MarkdownPad este cel mai popular editor markdown pentru Windows. Este optimizat pentru postările de pe bloguri, site-uri web, articole, README-uri și, bineînțeles, documentația software.

Puteți obține MarkdownPad gratuit, sau puteți obține versiunea premium pentru 14,95 $.

iA Writer (Mac)

iA Writer este un editor markdown simplu și frumos, cu o funcție de bibliotecă, ceea ce înseamnă că puteți face cu ușurință referințe la alte documente în bara laterală. Îi lipsesc legăturile interne între documente, așa cum v-ați aștepta să existe în documentele software, dar puteți oricând să faceți o trecere la acestea atunci când va fi în forma finală (adică dacă va ajunge pe internet într-un site).

Dacă vă scrieți întreaga documentație într-o singură pagină despărțită, puteți folosi ancore de salt de pagină pentru a ajuta utilizatorii să navigheze.

iA Writer costă 9,99 dolari din Mac App Store.

Profs Knowledge Base

Profs Knowledge Base este un mic instrument fantastic pentru toate etapele de creare a documentelor; de la scriere și editare, până la personalizare, stabilirea fluxurilor de lucru și publicare. Puteți adăuga multimedia, importa conținut existent din documente Word, PDF sau PPT, salva mai multe versiuni ale documentului și le puteți restaura la nevoie.

Dar adevărata frumusețe a acestui instrument constă în capacitatea sa de utilizare. Oricine și oricine îl poate folosi pentru a crea documentație software. Fie că documentați software de ani de zile, fie că ați început de curând, este un instrument incredibil de simplu și ușor de utilizat.

Profs poate fi utilizat gratuit, sau puteți trece la pachetul premium, care costă 112 dolari pe lună.

SimpleMDE (browser)

Chiar dacă, din punct de vedere tehnic, puteți scrie markdown în orice editor de text, deoarece este o modalitate de formatare a textului simplu, nu strict un „instrument”, nu vă va surprinde faptul că este posibil și în browser! SimpleMDE este atât un editor markdown funcțional construit pe JavaScript, cât și un proiect open-source din care puteți învăța și pe care îl puteți adapta pentru uz propriu, dacă este necesar.

SimpleMDE este 100% gratuit! Obțineți sursa pe GitHub aici.

Editori reStructuredText

Markdown este unul dintre cele două limbaje cel mai des folosite pentru scrierea documentației software, dar mai există un altul pe care nu l-am analizat până acum, și acesta este reStructuredText. Este foarte asemănător cu markdown, dar merită învățat în scopuri de documentare software.

Docutils, creatorul reStructuredText, a alcătuit o listă de editori reStructuredText aici, care include:

Principiul reStructuredText este că este ușor de convertit între diferite formate, în special de la text simplu la un site web static. Vedeți mai multe informații aici.

Instrumente pentru generarea automată a documentației din codul sursă

Nimic nu se compară cu atingerea umană atunci când vine vorba de documentație (se vede clar în documentele Slack și Giphy, pentru a numi doar câteva). Cu toate acestea, ca punct de plecare (în special pentru bibliotecile sursă uriașe), cel mai bine este să generați automat documentația scheletului. Acest lucru funcționează prin analizarea funcțiilor și comentariilor sursei și există câteva opțiuni diferite în funcție de limbă:

Înainte de a vă baza doar pe generarea automată, vă sugerez să citiți acest fir de discuție de pe StackExchange care cântărește argumentele pro și contra.

Cuvinte finale despre documentația software

Există o mulțime de soluții fanteziste, rezolvări rapide și instrumente care sunt (foarte sincer) aproape identice. Ceea ce contează în cele din urmă este că

Ceea ce contează cel mai mult, în cele din urmă, este că:

a) să scrieți documentația software pentru fiecare bucată de software pe care o construiți
b) să o scrieți în mod cuprinzător și să o găzduiți undeva unde utilizatorul poate accesa

Am menționat mai devreme că am mai multe șabloane de procese de dezvoltare pe care ați putea fi dornici să le verificați?

Bine, iată-le aici…

Process Street development process process templates

Înainte de a vă oferi aceste șabloane, dați-mi voie să vă explic ce este Process Street un pic mai mult.

Așa că știm că Process Street sunt liste de verificare super-putere. Este o bucată de software care vă va ajuta să creați și să gestionați procesele.

Dar așteptați, Process Street este mai mult decât atât!

Vizionați acest videoclip introductiv pentru a afla la ce mă refer:

Așa că, vedeți, nu numai că puteți crea un șablon de proces de dezvoltare și puteți rula liste de verificare individuale din acesta de fiecare dată când trebuie să finalizați procesul de dezvoltare, dar îl puteți personaliza folosind aceste caracteristici suplimentare

• Stop task-uri
• Date de scadență dinamice
• Permisiuni pentru task-uri
• Logică condiționată
• Aprobare task-uri
• Embed widget
• Asigurări de roluri

Asemnați task-uri, obțineți aprobarea, impuneți o ordine în care sarcinile sunt finalizate și puteți conecta procesul la mii de aplicații prin Zapier, webhooks sau integrare API.

Vizionați acest webinar despre cele mai noi caracteristici ale noastre și vedeți cum puteți profita la maximum de ele:

Cu toate acestea în minte, aruncați o privire la șabloanele pre-fabricate de mai jos:

Listă de verificare a auditului de securitate a rețelei

Acest șablon poate fi folosit de un manager de risc sau de un profesionist IT echivalent pentru a evalua o rețea pentru vulnerabilități de securitate.

Click aici pentru a accesa Lista de verificare a auditului de securitate a rețelei!

Listă de verificare pentru întreținerea lunară a site-ului web

Utilizați această listă de verificare pentru întreținerea lunară a site-ului web pentru a optimiza viteza de încărcare a site-ului dvs., pentru a căuta vulnerabilități și pentru a vă revizui vizibilitatea în căutări.

Click aici pentru a accesa Lista de verificare pentru întreținerea lunară a site-ului web!

Tutorial de testare a software-ului

Acest proces poate fi utilizat pentru a gestiona un întreg proiect de dezvoltare software de la început până la sfârșit, inclusiv proiectarea, manipularea clienților și, de asemenea, verificări după lansare.

Click aici pentru a accesa Tutorialul de testare software!

Și iată-l.

Ești acum liber să folosești orice îți face viața mai ușoară. Sper că veți găsi noul dvs. instrument preferat în această listă.