VuePress: Documentația simplificată
Publicat: 2022-03-10Când vine vorba de orice proiect care necesită orice interacțiune cu utilizatorul (de exemplu, utilizatori finali, întreținerii etc.), există un factor critic care face diferența între succes și eșec: o documentare bună. Acest lucru este valabil indiferent de cât de mic sau de mare este proiectul dvs. La urma urmei, fără a oferi asistență individuală pentru proiectul dvs., documentația este prima linie de apărare pentru utilizatorii care încearcă să rezolve o problemă. Și indiferent dacă vă place sau nu, nu veți auzi niciodată de la utilizatori care renunță după ce nu au putut să-și rezolve problema din cauza documentației inadecvate.
Provocările creării unei documentații bune
Când vine vorba de scrierea unei documentații bune, există patru probleme recurente pe care echipele le întâmpină adesea:
- Documentația este adesea depășită.
Deși nicio documentare pentru un proiect nu poate fi o experiență frustrantă, este probabil mai rău să ai documentație învechită . La urma urmei, scopul de a avea documentație este de a oferi utilizatorilor un corp oficial de cunoștințe pe care se pot baza. Când este învechit, utilizatorii își pierd timpul și, în cele din urmă, își pierd încrederea în produsul dvs.
Motivul principal pentru care documentația devine învechită este că întreținerea documentației este separată de modificările codului . Fără a investi timp și energie semnificativă, acest lucru poate fi dificil de rezolvat deoarece:- Documentația se află de obicei într-un serviciu terță parte, cum ar fi Confluence sau un Wiki,
- Dezvoltatorii sunt de obicei mai interesați să scrie cod decât să documenteze.
- Utilizatorii nu pot oferi cu ușurință feedback.
Indiferent cât de bună credeți că este documentația dvs., în cele din urmă este lipsită de sens fără a o testa cu utilizatori reali care pot oferi feedback. După cum am menționat mai devreme, o părtinire obișnuită atunci când se evaluează eficacitatea unor lucruri precum documentarea este că nu ține cont de utilizatorii care nu au putut să-și rezolve problemele și au renunțat. Întrucât nicio echipă nu ar fi capabilă să țină seama de fiecare scenariu despre modul în care utilizatorii ar putea folosi produsul dvs., utilizatorii trebuie să aibă o modalitate ușoară și fiabilă de a oferi feedback. - Documentația este adesea scrisă de utilizatorii cu putere pentru utilizatorii cu putere.
Defectul utilizării instrumentelor standard, cum ar fi wiki-urile sau fișierele README este că deseori se adresează doar unui anumit set de utilizatori care au adesea cunoștințe preexistente despre bibliotecă și/sau stiva de tehnologie. Drept urmare, este destul de simplu pentru ei să navigheze în spațiu și să găsească ceea ce au nevoie. Cu toate acestea, utilizatorilor noi le lipsesc aceste cunoștințe anterioare și, prin urmare, necesită adesea o experiență mult mai captivantă pentru a-i implica.
Exemple în acest sens includ:- Un site web bine conceput,
- Capacitate de căutare,
- Navigare laterală ghidată,
- Meta informații ușor de identificat (adică, data ultimei actualizări),
- Conținut captivant care se extinde dincolo de un perete de text greu de înțeles.
- Infrastructură slabă care face documentația dificil de întreținut.
De parcă scrierea unei documentații bune pe care utilizatorii o pot înțelege nu este suficient de dificilă, ușurința cu care un dezvoltator poate scrie și/sau menține documentația este esențială pentru viabilitatea pe termen lung. Deci, pentru fiecare barieră suplimentară cu care trebuie să se confrunte dezvoltatorii pentru a scrie și/sau a menține documentația, cu atât este mai probabil ca aceasta să eșueze în cele din urmă. Ca rezultat, este esențial ca experiența de creație și întreținerea oricărei documentații să fie cât mai fluide și captivante posibil.
Dacă ar exista un instrument care ar putea face toate aceste lucruri pentru noi...
Introduceți VuePress
La prima audiere despre VuePress, cineva ar putea fi tentat să ghicească că este o amalgamare a Vue.js și WordPress. În schimb, ar trebui să vă gândiți la VuePress ca:
Vue.js + tipar
Pentru că atunci când totul este spus și gata, VuePress este un generator de site static!
Unii dintre voi s-ar putea să se gândească: „Stai. Un alt generator de site static? Care este marea problemă?”
Deși există o serie de instrumente care sunt generatoare de site-uri statice, VuePress iese în evidență dintre pachet pentru un singur motiv: directiva sa principală este de a facilita dezvoltatorilor să creeze și să mențină o documentație excelentă pentru proiectele lor.
De ce este VuePress atât de puternic pentru a crea documentație?
Răspunsul este simplu. A fost conceput cu un singur obiectiv în minte: să ajute dezvoltatorii să creeze site-uri excelente de documentare, menținând în același timp o experiență de creație distractivă. Aceasta înseamnă că oferă un cadru pentru dezvoltatori pentru a:
- Creați site-uri frumoase de documentare,
- Vin cu funcții prefabricate esențiale pentru toate site-urile de documentare,
- Optimizați experiența de creație pentru a o face la fel de simplă precum actualizarea unui fișier Markdown.
VuePress poate coexista cu baza dvs. de cod existentă
Acesta este unul dintre motivele principale pentru care îl recomand cu căldură. Când vine vorba de întreținerea documentației, o modalitate de a garanta că aceasta va depăși este de a îngreuna dezvoltatorii să actualizeze documentele atunci când scriu cod. Dacă îngreunați experiența de creație, forțând dezvoltatorii să actualizeze lucrurile în două locuri diferite, acest lucru va cauza o mulțime de frecări și deseori va duce la lăsarea documentației pe margine. Acest lucru se vede de obicei atunci când dezvoltatorii trebuie să întrețină un instrument terță parte, cum ar fi un wiki, în plus față de baza de cod în sine.
Deoarece este un generator de site static, aceasta înseamnă că poate trăi în același repo exact ca și codul dvs.
După cum puteți vedea în acest exemplu de structură a aplicației web, codul dvs. ar locui în directorul src ca de obicei, dar veți avea pur și simplu un director docs pentru a conține toată documentația. Aceasta înseamnă că beneficiați de:
- Toată documentația este acum controlată de versiune;
- Solicitările pull pot conține acum atât documentație, cât și modificări de cod;
- Crearea de scripturi separate pentru rularea instanțelor locale ale codului și documentelor dvs. în același timp;
- Utilizați conductele de construcție pentru a determina dacă noile implementări ale site-ului de documentație sunt sincronizate cu implementările de cod sau nu.
Tema implicită vine cu o configurație standard
Scrierea documentației este destul de dificilă așa cum este, așa că VuePress descarcă multe dintre deciziile pe care trebuie să le ia în mod normal și are o grămadă de setări implicite încorporate pentru a vă ușura experiența de creație:
- Scrierea conținutului se face în principal cu Markdown.
Aceasta înseamnă că vă puteți valorifica cunoștințele existente despre sintaxa Markdown pentru a vă stila și formata textul.
- Evidențierea sintaxei codului.
Dacă ai construi un site pe cont propriu, ar trebui să te lupți cu bibliotecile de evidențiere a sintaxei de culoare. Dar aveți noroc pentru că puteți adăuga blocuri de cod în VuePress este atât de ușor, deoarece totul este gata să meargă cu configurație zero.
- Materia primară pentru definirea metadatelor la nivel de pagină.
Chiar dacă creați un fișier Markdown, puteți utiliza materialul din față (cum ar fi YAML, JSON sau TOML) pentru a defini metadatele pentru pagina dvs., pentru a facilita gestionarea conținutului dvs.!
--- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---- Containere personalizate Markdown.
În cazul în care nu știați, Markdown are extensii pentru a adăuga și mai multe comenzi rapide utile pentru a crea componente frumoase ale UI, cum ar fi containere personalizate. Și, deoarece sunt atât de utile în documentație, VuePress l-a configurat deja, astfel încât să îl puteți utiliza imediat:
Funcționalitate de căutare încorporată
Hai sa recunoastem. Indiferent de cât timp petrecem scriind documentație grozavă, în cele din urmă va fi inutil dacă utilizatorii nu o pot găsi. Există, în general, două abordări în acest sens:
- Așteptați ca roboții motoarelor de căutare să acceseze cu crawlere încet site-ul dvs. în speranța că într-o zi utilizatorii dvs. vor putea găsi pagina potrivită pe site-ul dvs. Nu este o soluție grozavă.
- Creați-vă propria funcționalitate de căutare, dar aceasta poate fi dificil de implementat pentru site-urile statice, deoarece nu rulează niciun cod pe server pentru a crea indecși de căutare și a efectua căutări. Ca să nu mai vorbim că acest lucru ia timp de dezvoltare de la produsul în sine. Deci nici asta nu este grozav.
Din fericire pentru noi, VuePress este aici pentru a salva ziua încă o dată!
VuePress vine cu o funcționalitate de căutare încorporată care generează propriul „motor de căutare” - ați citit bine. Fără nicio configurare sau configurare suplimentară a bazei de date, VuePress este configurat pentru a răzui întregul document pentru a genera un motor de căutare simplu care va prezenta utilizatorilor dvs. toate h1s și h2s.
Acum, unii dintre voi s-ar putea să se gândească,
„Dacă vreau ceva care să ofere indexare de nivel inferior pentru căutare?”
Ei bine, VuePress v-a acoperit și acolo, deoarece este conceput pentru a se integra cu ușurință cu Algolia DocSearch, care vă poate oferi această funcționalitate gratuit dacă îndepliniți cerințele lor:
Navigarea în bara laterală este la fel de simplă ca și activarea sau dezactivarea funcției
Pentru oricine a fost vreodată responsabil pentru gestionarea conținutului, știți cât de complicat poate fi să construiți o bară laterală care să aibă elemente imbricate și apoi să urmăriți în ce poziție se află cititorul în timp ce derulați în jos. Deci, de ce să-ți petreci timpul pe asta, când ai putea scrie documente mai bune? Cu VuePress, bara laterală este la fel de simplă precum comutarea pe prima pagină pentru o pagină:
Generarea automată de metadate importante care sunt de obicei trecute cu vederea
Unul dintre cele mai frustrante lucruri pe care le poate întâlni un utilizator este documentația învechită. Când un utilizator urmează pașii și are dificultăți în a înțelege de ce ceva nu funcționează, a putea afla cu ușurință ultima dată actualizată poate fi incredibil de util atât pentru utilizator, cât și pentru întreținerii proiectului.
Cu o configurație simplă, VuePress poate asigura afișarea automată a ultimei date actualizate pe pagină, astfel încât utilizatorii să știe întotdeauna când a fost actualizată ultima dată.
În plus, cu puțină configurație, VuePress face, de asemenea, incredibil de ușor pentru utilizatori să contribuie la documentele dvs. prin generarea automată a unui link în partea de jos a fiecărei pagini, care le permite utilizatorilor să creeze cu ușurință o cerere de extragere către documentele dvs.
Nu devine mult mai ușor decât atât pentru utilizatorii tăi.
Implementare pe orice site de găzduire statică
Deoarece VuePress este un generator de site static la bază, aceasta înseamnă că îl puteți implementa pe orice platformă de găzduire populară, cum ar fi:
- Netlify
- Pagini GitHub
- Pagini GitLab
- Heroku
- Acum
Tot ce trebuie să faceți pentru a construi site-ul este să rulați vuepress build {{ docsDir }} cu locul în care se află directorul dvs. și veți avea tot ce aveți nevoie pentru a-l implementa live pe web!
Notă : Pentru mai multe ghiduri aprofundate despre cum să faceți acest lucru, consultați ghidurile oficiale de implementare pentru VuePress.
Utilizarea Vue în interiorul fișierului Markdown
Știu, știu. Putem folosi Vue.js în Markdown nostru?! Da, ai citit bine! Deși este opțional din punct de vedere tehnic, acesta este probabil unul dintre cele mai interesante aspecte ale VuePress, deoarece vă permite să vă îmbunătățiți conținutul Markdown așa cum nu ați mai putut face niciodată înainte.
Definiți datele repetitive într-un singur loc și actualizați-le peste tot prin interpolare
În exemplul de mai jos, veți vedea un scurt exemplu despre cum puteți utiliza variabilele locale (cum ar fi cele definite în prima pagină), precum și pe cele definite la nivel global (cum ar fi titlul site-ului):
--- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!Utilizați componentele Vue în Markdown
Vă voi acorda un moment să vă adunați după ce ați citit acest lucru, dar da, componentele Vue live cu o instanță Vue completă vă pot fi luate dacă doriți! Va fi nevoie de ceva mai multă muncă pentru configurare, dar acest lucru este de așteptat, deoarece creați conținut personalizat care va rula în documentația dvs.
Iată un exemplu rapid despre cum ar arăta o componentă Counter într-un fișier Markdown:
Aceasta este poate cea mai puternică parte a personalizării disponibilă pentru documentație, deoarece înseamnă că acum aveți libertatea de a crea conținut personalizat, care depășește cu mult abilitățile Markdown standard. Deci, fie că este vorba de o demonstrație sau de un cod interactiv, ideile sunt nesfârșite!
Pasii urmatori
Dacă doriți să configurați un site de documentare frumos pentru ca utilizatorii să învețe cum să vă folosească produsul, nu devine mult mai ușor decât VuePress. Și chiar dacă ar putea fi ușor să presupunem că VuePress ar trebui să fie folosit numai de proiecte care folosesc Vue.js, acest lucru nu ar putea fi mai departe de adevăr. Iată doar câteva exemple de diferite tipuri de proiecte care folosesc VuePress pentru site-urile lor de documentare:
- Creați CMS
- UmiJS (care este creat pentru React)
- openHAB
- Păun
La sfârșitul zilei, indiferent dacă utilizați sau nu VuePress, sper că acest lucru v-a ajutat să vă inspirați să creați o documentație mai bună pentru utilizatorii dvs.
Resurse suplimentare
Există multe lucruri interesante pe care nu le-am acoperit aici în acest articol (de exemplu, tematică, blogging și așa mai departe), dar dacă doriți să aflați mai multe, consultați aceste resurse:
- Documente oficiale VuePress
- O listă organizată de resurse legate de VuePress
- Galeria VuePress
- VuePress Blog Boilerplate