Share
Ce veți creaDocumentarea unui proiect poate fi o provocare, dar nu trebuie să fie. Există destul de puține instrumente acolo pentru a face treaba - eu folosesc adesea Daux.io din cauza flexibilității sale.
În acest articol vă voi arăta de ce ar trebui să documentați, cum puteți obține Daux.io și cum puteți începe să îl utilizați chiar acum pentru a vă face proiectele mult mai bune.
Scrierea documentației pentru proiectul dvs. ar putea fi cea mai importantă decizie pe care o luați. Motivul pentru care acest lucru este adesea ignorat pentru proiectele bazate pe web este că nu sunt prea multe lucruri în joc.
Luați un Boeing 787 de exemplu. Acest produs are un corp amplu de documentare care susține fiecare aspect, de la proiectare la întreținere. Există chiar și un manual de aproape 150 de pagini care documentează caracteristicile 787 care trebuie luate în considerare la planificarea aeroporturilor.
De ce ar trebui ca un avion să aibă o documentație larg răspândită în timp ce un site web nu o face?
Cred că există trei motive principale:
Site-urile rareori au preocupări legate de siguranță, dar de îndată ce scara sau banii își reiau capul, puteți fi siguri că documentația va apărea. Toate proiectele mari, cum ar fi Twitter și Facebook, au o cantitate uluitoare de informații disponibile pentru dezvoltatori, atât la nivel intern cât și la terți.
Site-urile web care generează o mulțime de venituri deseori aleg să creeze o documentație bună. Ideea fiind că dacă ceva trebuie modificat, toată lumea se poate referi la documentație, iar site-ul este mult mai puțin probabil să piardă bani din cauza pierderii timpului de funcționare.
Acest lucru înseamnă că puteți obține fără documentație pentru un proiect mai mic? Sigur că da, întrebarea este: dacă ar trebui?
Documentația oferă un cadru de referință comun pentru un proiect. Beneficiul acestui lucru este destul de evident când lucrați într-o echipă, dar este trecut cu vederea când cineva lucrează singur.
Dacă îți faci site-urile de clădiri vii, șansele sunt să construiești cel puțin câteva pe an. Îți amintești cum un site pe care l-ai construit în ianuarie îți auto-tweets conținutul când vii să-l vezi în luna august? Ce se întâmplă dacă o companie vă cere să predați un proiect unui alt dezvoltator? Este posibil să vă petreceți o oră în fiecare dimineață în timp ce răspundeți la întrebări despre codul dvs. pentru luna următoare.
Chiar și cel mai consistent coder este inconsistent. Pe masura ce crestem si invatam tendinta de a schimba modul in care lucram. Poate că ați introdus un instrument de construcție cum ar fi Gulp în fluxul de lucru, poate că ați început să folosiți PHP orientat pe obiecte.
Documentația poate explica, de asemenea, situații care nu sunt evidente în codul însuși. S-ar fi putut alege o soluție sub-par, pentru că ați fost rugați să faceți ceva rapid și scopul a justificat mijloacele. Acest lucru poate fi adăugat la documentație, poate ca o sarcină de upgrade ulterior.
Daux.io poate sperieri pe unii oameni la început, deoarece nu este doar simplu HTML, ci poate fi previzualizat doar folosind un server. Cu toate acestea, setarea totul este destul de simplă și odată ce sari acest obstacol, utilizarea este ușor și flexibil.
Cel mai simplu mod de a obține Daux.io este să îl descărcați de la Github. Puteți descărca pachetul utilizând Descărcați ZIP pe bara laterală dreaptă. Dacă sunteți un utilizator Github cu experiență, îl puteți clona, sau îl puteți apuca de la ambalator prin compozitor.
Dacă descărcați de la Github ar trebui să se încheie cu un dosar numit "daux.io-master".
Redenumiți acest lucru la "documentație" și mutați-l pe desktop pentru claritate. Pentru a vă scrie documentația, nu o faceți nevoie orice. Puteți edita fișierele Markdown în orice editor și utilizați o comandă pentru a le converti în HTML pentru a le partaja ușor. Cu toate acestea, este mai bine să previzualizăm munca noastră pe măsură ce mergem, așa că vom face o pregătire pentru asta.
Pentru a previzualiza documentele, vom avea nevoie de un server. Din fericire, totul este furnizat în dosarul proiectului Daux.io, avem nevoie doar de pre-cerințele pentru a rula serverul: npm și Grunt.
Cel mai simplu mod de a apuca npm (Node Package Manager) este să instalați nodul. Accesați site-ul Nod și descărcați programul de instalare. Odată instalat, ar trebui să puteți utiliza comanda npm în terminal (pe Linux / OS X) sau în linia de comandă (Windows).
Notă rapidă: Voi face referire la linia de comandă de pe Windows și pe terminalul de pe Linux / OS X cu același cuvânt: Terminal.
Următorul lucru de care aveți nevoie este Grunt. Grunt este de fapt instalat prin intermediul npm, deci dacă ați terminat deja ultimul pas ar trebui să fie foarte simplu. Deschideți terminalul și tastați următoarea comandă:
npm instalare -g grunt-cli
Acum aveți instrumentele de bază necesare pentru a începe. Dacă sunteți nou la npm I recomandăm foarte mult să aflați mai multe despre el. Acesta vă permite să instalați cu ușurință unelte și nu trebuie neapărat să știți Node.js pentru a utiliza instrumentele de lucru cu npm (cum ar fi Grunt).
Totul până la acest punct este necesar numai dacă nu aveți deja aceste instrumente instalate. Indiferent câte exemple de documentație Daux.io aveți în jur, nu va trebui să faceți asta din nou.
Bacsis: aflați mai multe despre instrumentele de linie de comandă, urmând seria începătorului Linia de comandă pentru Web Design de Kezz Bracey.
Acest pas este numai pentru utilizatorii de Windows, OS X și majoritatea distribuțiilor Linux sunt preinstalate cu PHP, deci dacă vă aflați pe aceste platforme puteți sări peste această secțiune. Din păcate, instalarea liniei de comandă PHP în Windows este un pic de hassle, aici este rularea în jos.
Faceți clic pe pagina de descărcări PHP și luați versiunea de PHP pe care o doriți. Am folosit versiunea "VC11 x86 Non Thread Safe" când testez. Am descarcat si am extras aceasta arhiva in directorul meu root, C: / si am redenumit directorul rezultat in "php". La sfârșitul procesului trebuie să aveți un director numit "php" în directorul principal C: / /, directorul ar trebui să conțină un "php.exe" undeva.
Apoi, va trebui să vă asigurați că comanda PHP poate fi rulată de oriunde. În Windows 7, cel mai simplu mod de a face acest lucru este să mergeți la meniul Start, faceți clic dreapta pe Calculator și selectați Proprietăți. Click pe Setari de sistem avansate în bara laterală stângă. Faceți clic pe Avansat tab, apoi pe variabile de mediu butonul din partea de jos.
Va trebui să faceți clic pe cale în panoul de sus și apoi Editați | ×. La sfârșitul valorii adăugați o referință de folder, ceva de genul: "C: \ Users \ Dani \ environment". Acesta ar trebui să fie un dosar din propriul dosar de utilizator. După ce ați terminat, salvați totul și creați acest dosar. (Dacă utilizați o versiune diferită de Windows, aruncați o privire pe Computerhope, listează cum să faceți acest lucru pe mai multe versiuni).
În acest director creați un fișier numit "phppath.cmd". Editați acest fișier utilizând orice editor de text și adăugați următorul conținut:
PATH =% PATH%; C: \ Utilizatori \ Dani \ mediu php -v
După ce ați terminat, navigați în acest dosar prin intermediul liniei de comandă tastând cd% userprofile% / mediu și executați următoarea comandă: phppath.
În cele din urmă, închideți promptul de comandă și redeschideți-l, php ar trebui să fie acum disponibil la nivel global. Din nou, aceasta este ceva ce trebuie să faceți doar o singură dată, și numai pe Windows.
Încă în terminalul dvs., navigați la dosarul proiectului. Amintiți-vă, acest lucru ar trebui să fie pe desktop-ul nostru în acest stadiu. În Windows, puteți folosi următoarea comandă pentru a ajunge la dosarul proiectului:
cd% userprofile% / Desktop / documentație
Pe OS X puteți utiliza următoarea comandă:
cd ~ / Desktop / documentație
Prima comandă pe care ar trebui să o emiteți este npm install. Odată ce a terminat cursa Actualizare npm pentru a vă asigura că totul este actualizat. Aceste comenzi instalează și actualizează toate dependențele Daux.io. Veți avea nevoie să faceți acest lucru pentru fiecare instanță de Daux.io pe care o aveți.
Suntem în sfârșit pregătiți să examinăm documentația noastră. Aceasta este acum o chestiune de o singură comandă, tot ce trebuie să faceți este să tastați mormăit în terminal (asigurați-vă că sunteți în dosarul de documentare la emiterea comenzii).
După câteva secunde de gândire, ar trebui să vedeți ceva de genul:
Acest lucru înseamnă că serverul este în curs de funcționare, este posibil ca o filă nouă să fi fost deja deschisă în browser. Dacă nu, aruncați o privire la IP afișat lângă "Ascultarea" în terminal și introduceți-l în browserul dvs. În exemplul meu, acest IP este "127.0.0.1:8085".
Notă: în unele cazuri, fila se deschide dar arată "nicio pagină nu a fost găsită" sau o eroare similară. În acest caz reîncărcați fila după câteva secunde, serverul poate necesita un pic mai mult timp pentru a inițializa.
Ar trebui să vedeți acum documentația implicită furnizată în browser. Vizualizarea pe care o vedeți este generată ad-hoc din fișierele Markdown de documentare. Acum, că putem vedea ce facem, să ne uităm la documentația scrisă.
În dosarul "documentație" trebuie să vedeți un dosar "docs". Aceasta conține documentația dvs. reală, orice altceva este pentru Daux.io să-și facă magia. Daux.io utilizează o convenție de numire specifică pentru a vă oferi un control deplin asupra ordinii paginilor.
Fiecare element din această pagină ar trebui să înceapă cu un număr și un subliniere. Cu cât este mai mare numărul din partea inferioară a paginii va fi în documentație. Dacă aveți nevoie de o singură pagină, creați un fișier Markdown (de ex .: 04_Updating_Plugins), dacă aveți nevoie de o structură ierarhică de pagini, creați un dosar (de exemplu: 05_Code_Styling).
Textul după număr determină numele paginii din documentație. Exemplele mele anterioare vor deveni "Updating Plugins" și "Styling Code". Asigurați-vă că utilizați numai caractere alfanumerice și subliniere, sublinierile vor fi convertite în spații.
De aici, navigați fără probleme, tot ce trebuie să faceți este să editați fișierele în stilul lui Markdown. Dacă nu sunteți familiarizați cu markdown, aruncați o privire la cheia de joc Markdown. Este în esență o metodă de marcare a textului (indicați titluri, link-uri, imagini etc.) fără cod HTML.
Dacă creați o secțiune cu subpagini utilizând un dosar, puteți specifica subpagini în același mod ca și înainte. În directorul creat, creați fișiere individuale care să pornească numele fișierului cu un număr (care dă paginii comanda acestuia) și numele pe care doriți să-l afișați.
Un alt lucru frumos Daux.io vă permite să faceți este să creați o pagină de destinație pentru secțiunile dvs. Întreaga documentație poate obține o pagină de destinație dacă creați un fișier "_index.md". Uitați-vă la exemplul implicit pentru a obține o simțire a formatării.
Fiecare secțiune poate avea și o pagină de destinație. Dacă o secțiune nu are o pagină de destinație, elementul de meniu de nivel superior nu face clic pe nicăieri, ci doar deschide lista subsecțiunilor. Dacă doriți ca intrarea de nivel superior să aibă o pagină proprie, creați un fișier "index.md" în dosarul secțiunii.
Unele proiecte pot necesita mai multe documentații. Un site web poate justifica o documentație a utilizatorului final și o documentație pentru dezvoltatori care ar conține informații diferite.
O modalitate de a gestiona mai multe necesități de documentare, cum ar fi aceasta, este de a crea mai multe instanțe de Daux.io. Acest lucru necesită totuși să rulați serverul separat și să setați din nou unele lucruri. Din fericire există o cale mai bună!
Uitați-vă la fișierul "global.json" din dosarul principal al documentației. Dacă deschideți acest lucru cu editorul de text, ar trebui să vedeți că docs_directory parametrul este setat la Documente. Creați o copie a directorului docs, denumiți-o "user_docs" și adăugați niște fișiere manechinuri diferite pentru a le putea spune în afară de documentația originală.
Acum schimbați docs_directory parametru pentru user_docs și reîncărcați documentația în browser. Acum vizualizați conținutul noului dosar. Acest lucru facilitează trecerea înainte și înapoi între documentații în zbor, fără a fi necesar să reporniți serverul sau să utilizați o altă instanță a Daux.io.
Desigur, la sfârșitul zilei trebuie să ne distribuim documentația. Acest lucru este cel mai bine făcut în formă HTML și Daux.io ne-a acoperit! În terminal, în directorul principal al documentației executați următoarea comandă:
php generate.php
Acest lucru va crea un dosar "static" cu toate fișierele HTML și activele necesare pentru a vizualiza documentația. Poți să comentezi acest dosar și să îl trimiți cuiva sau să îl încarci pe un server și să îl trimiți la el.
Există o grămadă de lucruri pe care le puteți controla prin fișierul "default.json". În mod implicit, va exista a Realizat de Todaymade link-ul din bara laterală alături de câteva link-uri de urmărire pe care nu aveți nevoie sau doriți să le personalizați proiectului. Pagina principală Daux.io listează opțiunile pe care le puteți utiliza în secțiunea "Configurare" de mai jos. sau doar consultați fișierul "default.json".
Poți să folosești "twitter": ["yourtwittername"] pentru a adăuga propriul link Twitter, de exemplu. Legăturile pot fi controlate utilizând Link-uri parametru, iată cum să adăugați un cuplu:
link-uri: "GitHub Repo": "https://github.com/yourgithubrepo", "Suport": "http://support.myproduct.com", "Made by Me": "http: // mywebsite .com "
Puteți găsi toate opțiunile de pe pagina principală Daux.io. Iată un exemplu de fișier complet "default.json" pentru un proiect imaginar.
"title": "Proiectul meu", "slogan": "Documentația mea stilată", "docs_directory": "docs", "valid_markdown_extensions": ["md", "markdown" "," twitter ": [" danielpataki "]," temă ":" daux-albastru "," breadcrumbs ": false," template ": default_code ": false," float ": false," link-uri ": " GitHub Repo ":" https://github.com/danielpataki/exampleproject "," Support ":" http://support.exampleproject.com " "Made by Daniel": "http://danielpataki.com"
Configurarea Daux.io poate părea la început o sarcină descurajantă, dar nu este așa de lungă, mai ales pe sistemele Mac / Linux unde majoritatea a ceea ce avem nevoie este preinstalată. Dacă nu sunteți obișnuit cu terminalele și cu serverele locale, poate dura puțin timp pentru a vă obișnui cu mediul, dar acest lucru va fi plătit de zece ori.
Odată ce te ridici și alergi cu Daux.io, vei descoperi că este ușor de utilizat, flexibil și ușor de întreținut. Proiectul dvs., clientul dvs., colegii dvs. și utilizatorii finali ai proiectului vă vor mulțumi tuturor pentru eforturile dvs. și, sperăm, timpul dvs. petrecut în susținerea proiectului va fi minimizat.
Accentsconagua