6 cele mai bune exemple de documentare software și cele mai bune practici

Vrei să știi succesul din spatele produselor software bune, înfloritoare?

Este documentația lor.

Companiile bune investesc foarte mult în documentația lor software. De fapt, primul lucru pe care îl fac este să creeze documentație care să includă scopul software -ului, domeniul de aplicare, lucrările sale și referințele din industrie.

Acest lucru permite părților interesate să arunce o privire asupra costurilor de dezvoltare software, a cronologiei, a unghiului de marketing și a strategiilor, a decalajului funcționalității și a funcțiilor cheie pe care să se concentreze.

Nu numai că ajută la dezvoltare, documentația software este una dintre cele mai utilizate metode pentru instruirea de noi angajați, la bordul clienților noi și oferirea de asistență.

De asemenea, am creat mai multe software și documentația lor, de la faptul că vă putem ghida cu documentația dvs. software .

Deci, să începem!

Testăm riguros și cercetăm fiecare produs pe care îl recomandăm prin eroteme. Procesul nostru de revizuire. De asemenea, putem câștiga un comision dacă faceți o achiziție prin legăturile noastre.

Ce este documentația software?

Documentația software este orice material scris sau video care ajută la dezvoltarea software -ului, procesele de dezvoltare a înregistrărilor și progresul, explică modul în care funcționează o aplicație software, ghidează utilizatorii folosind software -ul în mod eficient și servește ca material de asistență pentru clienți.

Tipuri de documentare software

Un proiect software poate dura câteva zile până la câțiva ani pentru a fi finalizat. Deci, înainte de a începe cu orice software de afaceri, este important să înțelegeți în ce vă scufundați.

Drept urmare, documentația software acoperă o gamă vastă de documentație. De la etape de planificare până la respectarea legilor.

Unele dintre documentele produse în ciclul de viață al dezvoltării software, sursa - CDS.cern.ch

Acest lucru vă va ajuta să vă faceți o idee generală despre cum să începeți documentația software și lucrurile pe care să le acoperiți.

1. Documentația proiectului

Documentarea proiectului este creată în etapele inițiale ale creării de software și menținută pe tot parcursul ciclului său de viață.

Deoarece oferă ochilor păsărilor asupra procesului de dezvoltare a software -ului, ajută foarte mult la luarea deciziilor.

Acoperă cercetarea, testarea, ideile, exemplele, alocarea resurselor, detaliile întâlnirii, progresul muncii, etapele și obiectivele viitoare.

2. Cerințe și documentație de proiectare

Cerințe și documentație de proiectare ambele funcționează din mână la mână. Este ca și cum ai crea o schiță aspră a software -ului tău înainte de a începe efectiv codificarea acestuia.

Include componente cheie, cum ar fi:

• Prezentare generală a sistemului
• Obiective și obiective la nivel înalt
• Cerințe funcționale
• Criterii de acceptare
• Arhitectură de sistem
• Tehnologia Stack

În timp ce documentația cerințelor se concentrează pe ceea ce ar trebui să facă sistemul, documentația de proiectare se concentrează asupra modului în care va fi construit sistemul.

Cele mai bune practici: este mai bine să enumerați toate cerințele dvs. din software și să le împărțiți în mai multe etape. Acest lucru vă va ajuta să proiectați un software mai bun de la început.

Multe software sunt reproiectate (de exemplu, rescrise într-un limbaj diferit sau re-structurat) pur și simplu pentru că nu a fost proiectat corect în primul rând.

3. Documentare tehnică

Documentația tehnică acoperă modul în care sistemele software sunt construite, operate și întreținute.

În documentația software trebuie să creați documentație tehnică pentru a explica:

• Cum funcționează codul
• API -uri (interfață de programare a aplicației)
• Schema bazei de date (tabele, relații și flux de date)
• Cum se actualizează dependențele software
• Ghiduri de depanare

Avem un ghid complet pentru crearea și scrierea documentației tehnice, verificați -l!

4. Documentația utilizatorului

Documentația utilizatorului îi ajută pe utilizatorii finali (clienții) să vă utilizeze software -ul în mod eficient.

Include:

• Manuale de utilizare : creat pentru utilizatorii finali. De exemplu, modul în care utilizatorii pot utiliza o anumită caracteristică a produsului dvs.
• Materiale de instruire: conține diverse resurse de instruire pentru utilizatorii finali. De exemplu, ghiduri de configurare, videoclipuri sau cursuri.

Documentația utilizatorului este puțin diferită de o documentație tehnică, avem câteva ghiduri care vă vor ajuta să aflați mai multe despre aceasta:

• 5 cele mai bune exemple de documentare pentru utilizator (sfaturi bune și rele +)
• Cum se creează un manual de utilizare: de la zero la erou (ghid complet)

5. Documentația de testare

Testarea documentației sau orientările create special pentru echipele QA (asigurarea calității). Pentru a asigura calitatea software -ului respectă standardele de piață sau răspunde cerințelor părților interesate.

Include:

• Plan de testare și cazuri de testare
• Liste de verificare de urmat în timp ce testați o caracteristică software
• Orientări privind calitatea codului
• Teste automate

6. Documentație de întreținere / securitate

Acest tip de documentație ajută dezvoltatorii și echipele să întrețină, să actualizeze, să depanseze și să depanați software -ul.

Include:

• Actualizați ghiduri sau liste de verificare
• Ghiduri pentru actualizarea dependențelor software
• Controluri de acces
• Plan de incidente
• Note de eliberare

7. Documentația legală și de conformitate

Documentația legală și de conformitate pentru a se asigura că software -ul respectă standardele legale, de reglementare și industrie.

Documente legale, cum ar fi:

• Acord de licență pentru utilizatorul final (EULA)
• Termeni de serviciu (TOS)
• Politica de confidențialitate
• Licențe software și informații de utilizare

Documente de conformitate, cum ar fi:

• Protecția datelor și respectarea confidențialității, care include reglementări precum GDPR, CCPA sau HIPAA.
• Respectarea securității
• Respectarea accesibilității
• Reglementări specifice industriei

Explorați : Ce este documentația software?

6 cele mai bune exemple de documentare software din care să înveți

1.. WordPress

Sunt șanse să fi folosit deja WordPress înainte, deci acesta ar putea fi cel mai bun exemplu de documentare software din care să înveți.

WordPress este utilizat pe 43% din toate site -urile web de pe web. Deci, documentația sa trebuie să fie una dintre cele mai bune pentru a servi milioane de oameni din întreaga lume.

Aceasta include dezvoltatori, designeri, bloggeri, scriitori sau oricine dorește să construiască un site web.

Documentația principală WordPress este împărțită în trei secțiuni diferite :

1. Aflați WordPress: include ghiduri sub formă de cursuri aprofundate, videoclipuri și tutoriale scrise. Vizat către începători, utilizatori intermediari și avansați.
2. Documentația principală: destinată utilizatorilor normali. Pentru a oferi o imagine de ansamblu a caracteristicilor WordPress, sub forma unor tutoriale scrise scurte scurte.
3. Resurse pentru dezvoltatori: destinate dezvoltatorilor care creează teme WordPress, pluginuri sau doresc să extindă WordPress cu codificarea personalizată. Include ghiduri de pornire, documentație API și exemple de codare.

În general, creează un hub de resurse perfect pentru oricine dorește să creeze un site web sau să înceapă cu WordPress. Este ușor de navigat, de a căuta prietenos, în profunzime, plin de exemple și foarte util.

Lucruri de învățat din documentația software WordPress:

• Ei își cunosc publicul , ca urmare, puteți vedea mai multe secțiuni de documentare și ghiduri create pe baza nivelului de cunoștințe sau a expertizei utilizatorului .
• Actualizări continue . Documentația software nu este un lucru unic, funcțiile software, UI sau funcționalitatea se pot schimba în timp. Același lucru s -a întâmplat și cu WordPress (de la tema clasică la blocarea temelor și a completării Gutenberg) și s -au asigurat să își actualizeze documentația cu fiecare actualizare.
• Forumuri de sprijin . În afară de tutoriale și ghiduri premade, WordPress include, de asemenea, un forum de asistență pentru fiecare plugin și temă. Acest lucru este foarte util în cazul în care utilizatorii au probleme de rezolvare a problemelor pe cont propriu.
• SEO (motor de căutare prietenos) . În cariera mea de peste 9 ani ca utilizator WordPress , am vizitat direct sau am răsfoit documentația WordPress direct. Tot ce am făcut a fost să caut pe Google și am găsit soluția la întrebările mele. Documentele WordPress și paginile de asistență generate de utilizator sunt ușor indexate pe Google (sau alte motoare de căutare) care vă permit să le găsiți cu ușurință.
• Întrebări frecvente . De cele mai multe ori FAQ -urile sunt ratate în documentație. Dar WordPress nu a ratat -o. Întrebări frecvente oferă informații instantanee sau o soluție și sunt ușor de scanat.
• Sistem de feedback . Puteți oferi feedback pentru fiecare ghid, ceea ce este o caracteristică utilă pentru găsirea de ghiduri învechite și inutile.

Ce să nu vă placă despre documentația WordPress:

• Fără documentație multilingvă . Deși puteți găsi cu ușurință ghiduri WordPress terțe în limba dvs. Dar aș dori ca WordPress să fi creat câteva tutoriale pentru limbi populare.

2. Baza de cunoștințe Herotemes

Documentația noastră software proprie.

Nu este cel mai bun exemplu de acolo, dar având în vedere că majoritatea dintre voi aveți o situație similară cu a noastră:

• Nici o idee de unde să începeți
• Buget redus

Poate fi un bun exemplu din care să înveți.

Herothemes oferă pluginuri de asistență pentru clienți, inclusiv bază de cunoștințe eroice care permite utilizatorilor să creeze o bază de cunoștințe sau site -uri de documentare fără cunoștințe de codificare, pentru uz public și intern.

Lucruri de învățat din documentația Herothemes Exemplu:

• Crearea numai a documentației necesare și îmbunătățirea acesteia. Herothemes are foarte puține ghiduri, având în vedere că majoritatea clienților vizați sunt nivel intermediar (dezvoltatori, utilizatori WordPress), iar software -ul este foarte simplu și simplu de utilizat.
• Cuprins (TOC) . Având în vedere că unele dintre aceste ghiduri conțin pasarele complete, TOC ajută la găsirea informațiilor necesare.
• Capturi de ecran . Întrucât majoritatea dintre noi nu poate scuti un buget bun pentru documentație (în special atribuirea unui designer pentru a crea imagini de calitate) de la început, adăugarea capturilor de ecran este mult mai bună decât să nu adăugați nimic. Cu toate acestea, imaginile create de designeri oferă într -adevăr o senzație premium.
• Documentație pentru a sprijini urmărirea biletelor .

Este una dintre funcțiile eroice KB Analytics pentru a urmări biletele de asistență provenite din documentație. Foarte util pentru a găsi un conținut nefolositor și învechit.

• Întrebări frecvente . Utilizatorii pun o mulțime de întrebări frecvente, cum ar fi politica de rambursare sau upgrade -urile viitoare, răspunzându -le prin documentație îi ajută pe utilizatori să le găsească cu ușurință cu o bară de căutare și asistent de ajutor AI.
• AI Ajutor asistent . Similar cu barele de căutare, AI Assistant ajută utilizatorii să găsească cu ușurință răspunsuri la întrebările lor. Este instruit pe conținutul documentației, astfel încât răspunsurile sunt relevante și utile.

Ce să nu vă placă la documentația Herotemes:

Deoarece Herothemes oferă mai multe soluții software, gruparea conținutului de documentare este un pic de mizerie .

Avem câteva ghiduri care să vă ajute să creați un site de documentare cu WordPress:

• Cum se creează o bază de cunoștințe WordPress (Ghid pas cu pas)
• Cum se creează o documentație internă

3. Documentația portofoliului de software Barn2

Barn2 vinde mai multe produse software bazate pe WordPress și WooCommerce care sunt utilizate pe peste 90.000 de site -uri web.

Servirea mai multor documentații software dintr -un singur portal poate fi dificilă, dar Barn2 o face frumos.

Cu siguranță ar trebui să te uiți la exemplul lui Barn2 dacă ai mai multe produse.

Lucruri de învățat din exemplul documentației Barn2:

Barn2 și -a conceput foarte atent pagina de asistență. Care poate fi văzută cu funcționalitatea și utilitatea sa generală.

Când vizitați pagina lor de asistență, veți găsi o bară de căutare proeminentă cu o opțiune pentru a selecta un anumit produs .

Întrebări frecvente legate de pre-vânzare, licențiere, actualizări și probleme tehnice. Acest lucru este foarte captivant să interacționeze și oferă și răspunsuri rapide .

Atunci când căutarea nu oferă rezultate, acesta arată o modalitate de a ajunge la sprijinul uman.

Vorbind despre documentația software principală:

• Veți găsi toate ghidurile importante în partea de sus , iar ghidurile sunt împărțite în diferite secțiuni pentru o navigare ușoară.
• Include tutoriale scrise și video.
• Suportul uman este ușor accesibil cu CTA bara laterală.
• Blocuri/modele personalizate pentru note, sfaturi, mesaje de avertizare și fragmente de cod pentru a îmbunătăți capacitatea de scanare.

Ce să nu vă placă despre documentația lui Barn2:

• Fără sistem de feedback . Deși oferă acces direct la sprijinul uman, nu există nicio modalitate pentru ei să adune feedback în timp real de la utilizatori. Ceea ce poate duce la informații și tutoriale învechite.

Barn2 folosește, de asemenea, o bază de cunoștințe eroice pentru a -și crea documentația software.

4. Ghidul utilizatorului iPhone

Există multe lucruri care să le placă și să nu placă cu privire la documentația utilizatorului iPhone (ghiduri software iOS).

Este o documentație software cu aspect fantezist, cu instrucțiuni ușor de urmărit, ceva de genul acesta pe care îl puteți aștepta de la Apple.

Lucruri de învățat din exemplul documentației iPhone:

Documentația iPhone pare uimitoare .

• O singură coloană de aspect
• O mulțime de spațiu alb
• Paragraf mic și conținut
• Vizuale frumoase
• Utilizare bună a titlurilor, listelor și divizoarelor

Cea mai mare parte a documentației lor este pe crearea unor astfel de ghiduri uimitoare și de ajutor vizual.

Când găsiți ghidul relevant, este nevoie de mai puțin de un minut să scanați și să înțelegeți ce să faceți.

Documentația iPhone este creată în mod special în acest fel, astfel încât toată lumea o poate înțelege cu ușurință.

Dacă doriți să creați documentație software de produse, vă recomandăm să creați ghiduri de utilizator similare cu iPhone -ul dacă aveți un buget pentru a rezerva documentația.

În afară de înfrumusețarea documentației lor, Apple nu a uitat să folosească corect SEO . A fi specific:

• Structura titlului și a titlului
• Interconectarea într -o formă de TOC, postări conexe, navigare anterioară și următoare

Sistemul de feedback de ghid este minunat . Faceți clic pe Da sau Nu, și dacă este nevoie, dați și feedback.

Sistemul de feedback nu sună atât de mișto, dar atunci când aveți milioane de utilizatori care vă oferă feedback, o simplă urmărire da sau nu este cu adevărat utilă pentru a verifica performanța ghidurilor (pur și simplu nu puteți citi toate acel feedback, nu -i așa?) .

Apple oferă, de asemenea, ghiduri bazate pe versiuni software (în acest caz, versiunea iOS).

Ce să nu vă placă despre documentația iPhone:

Am lăudat multe despre documentația iPhone de mai sus, dar există și câteva lucruri enervante.

În special partea de navigare.

• Cuprinsul nu este util, deoarece include toate legăturile de ghidare.
• Pictograma de căutare este prea mică pentru a fi observată.

5. Document de proiectare software (exemplu intern)

Documentația software pornește chiar de a crea orice software.

De exemplu, documentația dvs. software inițială ar putea include:

• Care sunt nevoile din software
• Sfera de aplicare
• Cum va funcționa
• Referințe

A avea informații detaliate va ajuta la evitarea multor întâlniri viitoare, la instruirea de noi angajați și la crearea de linii directoare concrete.

Puteți învăța multe din documentul de proiectare a software -ului Road Trip Advisor.

Prezintă toate cerințele necesare pentru a începe construirea de software (în acest caz, o aplicație web) sau pentru a ajuta noii angajați să înțeleagă cerințele din software.

Mai mult, îl puteți îmbunătăți întotdeauna în timpul dezvoltării de software.

Lucruri de învățat din acest exemplu:

• Include informații de bază, dar importante, cum ar fi scopul, domeniul de aplicare și definițiile care creează orientări concrete.
• Utilizarea diagramelor și a graficii vizuale pentru a ajuta dezvoltatorii să înțeleagă mai bine cerințele. De exemplu: descrierea conexiunilor sau fluxului funcționalității cu diagrame.

6. Documentația Google

Cine nu știe Google? Folosim în fiecare zi software-ul lor de top-of-line, cum ar fi Chrome, Gmail, Google Maps, Google Drive sau YouTube.

Sunt disponibile atât pentru computer, cât și pentru dispozitive mobile. Diferite sisteme de operare, dispozitive, rezoluții și setări.

Într -o astfel de situație, trebuie să fie un coșmar pentru a crea ceva bun fără o mizerie. Și Google face o treabă foarte bună cu documentația lor .

Lucruri de învățat din documentația software a Google:

• Utilizare excelentă a filelor și acordeonului pentru a simplifica grupurile de conținut.

Dacă creați software pentru mai multe dispozitive, acesta este modul în care puteți evita crearea mai multor documente.

• Sistem minunat de feedback. Similar cu unele dintre exemplele de mai sus, Google include, de asemenea, un sistem de feedback da/nu, care colectează și feedback de la utilizatori.

Dar Google face un pas mai departe aici. Au un sistem în vigoare care colectează feedback pe baza unor secțiuni specifice . Ceea ce este foarte intuitiv și la îndemână.

• Conținut rapid . Accesați acolo, faceți clic pe acest lucru, descărcați, instalați și boom. Așa se simt rapid tutorialele de documentare Google.
• Bare de top pentru a accesa rapid căutarea, centrul de ajutor, comunitatea și pagina de produs.
• Documentație disponibilă în mai multe limbi .

Ce să nu vă placă despre documentația Google:

Am încercat să găsesc multe despre care să mă plâng aici, dar până la urmă nu am putut să o fac. Google sigur are o documentație software bună.

Gânduri finale

Am acoperit o mulțime de exemple diferite în acest ghid de exemple de documentare software și ne -am împărtășit și experiența personală.

Iată câteva cuvinte finale:

1. Când începeți cu crearea de software , creați câteva ghiduri interne care vor contura scopuri software, domeniu de aplicare, funcționalitate și criterii de lansare.
2. Construiți portofoliul de documentare pe măsură ce dezvoltați software . De exemplu, documentația API și documentația tehnică.
3. Înainte de a lansa software -ul , creați documentație de utilizator care include ghiduri de configurare, cazuri de utilizare, prezentare generală a funcționalității și întrebări frecvente.
4. După lansare , creați tutoriale pentru a aborda cele mai comune probleme de utilizator și pentru a vă îmbunătăți documentația veche.

Documentația nu este o glumă; Vă poate salva de la originea de reamenajare a software -ului sau de reproiectare a proceselor. Vă pot ajuta să oferiți o experiență mai bună pentru clienți și să păstrați clienții.

Dacă sunteți în căutarea unei soluții de documentare software , Heroic Knowledge Base are totul de oferit pe care l -am discutat în acest ghid.

Încearcă!