Share
Cosa starai creandoDocumentare un progetto può essere una seccatura, ma non è necessario. Ci sono parecchi strumenti là fuori per portare a termine il lavoro: spesso uso Daux.io a causa della sua flessibilità.
In questo articolo ti mostrerò il motivo per cui dovresti documentare, come puoi ottenere Daux.io e come puoi iniziare ad usarlo in questo momento per rendere i tuoi progetti molto migliori.
Scrivere la documentazione per il tuo progetto potrebbe essere la singola decisione più importante che prendi. La ragione per cui questo è spesso trascurato per i progetti basati sul web è che non c'è molto in gioco.
Prendi un Boeing 787 per esempio. Questo prodotto ha una vasta documentazione che supporta ogni aspetto dalla progettazione alla manutenzione. C'è anche un manuale di circa 150 pagine che documenta le 787 caratteristiche da tenere in considerazione durante la pianificazione degli aeroporti.
Perché un aeroplano dovrebbe avere una documentazione di ampia portata mentre un sito web no?
Credo che ci siano tre ragioni principali:
I siti web raramente hanno problemi di sicurezza, ma non appena la bilancia oi soldi si alzano in testa puoi essere sicuro che la documentazione apparirà. Tutti i progetti di grandi dimensioni come Twitter e Facebook offrono incredibili quantità di informazioni disponibili per gli sviluppatori, sia a livello interno che di terze parti.
I siti web che generano molto reddito spesso scelgono anche di creare una buona documentazione. L'idea è che se qualcosa deve essere modificato tutti possono fare riferimento alla documentazione e il sito Web ha meno probabilità di perdere denaro a causa della perdita di tempo di attività.
Questo significa che puoi ottenere senza documentazione per un progetto più piccolo? Certo, la domanda è: dovresti?
La documentazione fornisce una cornice comune di riferimento per un progetto. Il vantaggio di questo è abbastanza ovvio quando si lavora in una squadra, ma è trascurato quando qualcuno sta lavorando da solo.
Se realizzi i tuoi siti web di costruzione viventi, è probabile che tu costruisca almeno un paio di anni. Ti ricorderai come un sito web che hai costruito a gennaio auto-tweets il suo contenuto quando lo guardi il prossimo agosto? Cosa succede se una società ti chiede di consegnare un progetto a un altro sviluppatore? Potresti trascorrere un'ora ogni mattina a rispondere a domande sul tuo codice per il prossimo mese.
Anche il coder più coerente è incoerente. Man mano che cresciamo e impariamo tendiamo a modificare il nostro modo di lavorare. Forse hai introdotto uno strumento di compilazione come Gulp nel tuo flusso di lavoro, forse hai iniziato a utilizzare PHP orientato agli oggetti.
La documentazione può anche spiegare situazioni che non sono ovvie nel codice stesso. Probabilmente hai scelto una soluzione sub-par semplicemente perché ti è stato chiesto di fare qualcosa velocemente e il fine ha giustificato i mezzi. Questo può essere aggiunto alla documentazione, forse come attività da aggiornare in seguito.
Daux.io può spaventare alcune persone all'inizio perché non è solo un semplice HTML, può essere visualizzato in anteprima solo tramite un server. Tuttavia, impostare tutto questo è abbastanza semplice e una volta superato questo ostacolo, l'utilizzo è semplice e flessibile.
Il modo più semplice per ottenere Daux.io è scaricarlo da Github. Puoi scaricare il pacchetto usando il Scarica ZIP pulsante sulla barra laterale destra. Se sei un utente esperto di Github puoi clonarlo, o puoi anche prenderlo da Packagist tramite il compositore.
Se scarichi da Github dovresti finire con una cartella chiamata "daux.io-master".
Rinominalo in "documentazione" e spostalo sul desktop per maggiore chiarezza. Per scrivere la tua documentazione in realtà non lo fai bisogno nulla. Puoi modificare i file Markdown in qualsiasi editor e utilizzare un comando per convertirli tutti in HTML per una facile condivisione. Tuttavia, è meglio vedere in anteprima il nostro lavoro mentre procediamo, quindi faremo una preparazione per questo.
Per visualizzare l'anteprima dei documenti avremo bisogno di un server. Fortunatamente, tutto è fornito all'interno della cartella del progetto Daux.io, abbiamo solo bisogno dei prerequisiti per eseguire il server: npm e Grunt.
Il modo più semplice per prendere npm (Node Package Manager) è installare il nodo. Vai al sito web del Nodo e scarica il programma di installazione. Una volta installato dovresti essere in grado di usare il comando npm nel terminale (su Linux / OS X) o nel prompt dei comandi (Windows).
Nota rapida: Mi riferirò al prompt dei comandi su Windows e al terminale su Linux / OS X con la stessa parola: terminale.
La prossima cosa di cui avrai bisogno è Grunt. Grunt viene effettivamente installato tramite npm, quindi se hai già completato l'ultimo passaggio dovrebbe essere semplicissimo. Apri il terminale e digita il seguente comando:
npm install -g grunt-cli
Ora hai gli strumenti di base necessari per iniziare. Se sei nuovo a npm consiglio vivamente di saperne di più. Ti permette di installare facilmente gli strumenti e non devi necessariamente conoscere Node.js per utilizzare gli strumenti di lavoro con npm (come Grunt).
Tutto ciò che serve fino a questo punto è necessario solo se non hai già installato questi strumenti. Non importa quante istanze di documentazione Daux.io hai in giro, non dovrai farlo di nuovo.
Mancia: scopri di più sugli strumenti della riga di comando seguendo le serie per principianti La riga di comando per il web design di Kezz Bracey.
Questo passaggio è solo per gli utenti Windows, OS X e la maggior parte delle distribuzioni Linux sono preinstallate con PHP quindi se sei su quelle piattaforme puoi saltare questa sezione. Sfortunatamente l'installazione della riga di comando di PHP in Windows è un po 'complicata, ecco il run down.
Vai alla pagina dei download di PHP e prendi la versione di PHP che desideri. Ho usato la versione "VC11 x86 non thread safe" durante il test. Ho scaricato ed estratto questo archivio nella mia cartella principale, C: / e rinominato la cartella risultante in "php". Alla fine del processo dovresti avere una cartella chiamata "php" nella tua directory C: / principale, la cartella dovrebbe contenere un "php.exe" da qualche parte.
Successivamente, dovremo assicurarci che il comando PHP possa essere eseguito da qualsiasi luogo. Su Windows 7, il modo più semplice per farlo è quello di andare al menu di avvio, fare clic destro su Computer e selezionare Proprietà. Clicca su Impostazioni avanzate di sistema nella barra laterale di sinistra. Clicca sul Avanzate scheda, quindi su variabili ambientali pulsante in basso.
Dovrai fare clic su sentiero nel riquadro superiore e poi modificare. Alla fine del valore aggiungi un riferimento alla cartella, qualcosa come questo: "C: \ Users \ Dani \ environment". Questa dovrebbe essere una cartella all'interno della tua cartella utente. Al termine, salva tutto e crea questa cartella. (Se usi una versione diversa di Windows dai un'occhiata a Computerhope, elenca come farlo su più versioni).
All'interno di questa cartella crea un file chiamato "phppath.cmd". Modifica questo file utilizzando qualsiasi editor di testo e aggiungi il seguente contenuto:
PERCORSO =% PERCORSO%; C: \ Utenti \ Dani \ ambiente php -v
Una volta fatto, navigare in questa cartella tramite il prompt dei comandi digitando cd% userprofile% / environment ed esegui il seguente comando: phppath.
Infine, chiudi il prompt dei comandi e riaprilo, php ora dovrebbe essere disponibile a livello globale. Ancora una volta, questo è qualcosa che devi fare solo una volta, e solo su Windows.
Sempre nel tuo terminale, vai alla cartella del progetto. Ricorda, questo dovrebbe essere sul nostro desktop in questa fase. Su Windows è possibile utilizzare il seguente comando per accedere alla cartella del progetto:
cd% userprofile% / Desktop / documentazione
Su OS X puoi usare il seguente comando:
cd ~ / Desktop / documentazione
Il primo comando che dovresti pubblicare è installazione di npm. Una volta completato, corri aggiornamento npm per assicurarsi che tutto sia aggiornato. Questi comandi installano e aggiornano tutte le dipendenze di Daux.io. Dovrai farlo per ogni istanza di Daux.io che hai.
Siamo finalmente pronti per vedere in anteprima la nostra documentazione. Ora si tratta di un comando, tutto ciò che devi fare è digitare grugnito nel terminale (assicurati di essere nella cartella della documentazione quando esegui il comando).
Dopo alcuni secondi di riflessione dovresti vedere qualcosa di simile a questo:
Ciò significa che il server è attivo e funzionante, una nuova scheda potrebbe già essere stata aperta nel tuo browser. In caso contrario, dai un'occhiata al IP visualizzato accanto a "Ascolto attivo" nel terminale e inseriscilo nel browser. Nel mio esempio questo IP è "127.0.0.1:8085".
Nota: in alcuni casi la scheda si apre ma mostra "nessuna pagina trovata" o qualche errore simile. In questo caso, ricaricare la scheda dopo un paio di secondi, il server potrebbe necessitare di un po 'più di tempo per l'inizializzazione.
Ora dovresti vedere la documentazione predefinita fornita nel browser. La vista che stai vedendo è generata ad-hoc dai file Markdown della documentazione. Ora che possiamo vedere quello che stiamo facendo, diamo un'occhiata alla documentazione scritta.
All'interno della cartella "documentazione" dovresti vedere una cartella "docs". Questo contiene la tua vera documentazione, tutto il resto è per Daux.io per fare la sua magia. Daux.io utilizza una convenzione di denominazione specifica per darti il pieno controllo sull'ordine delle pagine.
Ogni articolo in questa pagina dovrebbe iniziare con un numero e un trattino basso. Più alto è il numero più in basso nella pagina sarà nella documentazione. Se hai bisogno di una singola pagina per creare un file Markdown (es: 04_Updating_Plugins), se hai bisogno di una struttura gerarchica di pagine, crea una cartella (es: 05_Code_Styling).
Il testo dopo il numero determina il nome della pagina nella documentazione. I miei esempi precedenti diventeranno "Aggiornamento plug-in" e "Stile codice". Assicurati di utilizzare solo caratteri alfanumerici e caratteri di sottolineatura, i caratteri di sottolineatura verranno convertiti in spazi.
Da qui in avanti è una navigazione fluida, tutto ciò che devi fare è modificare i tuoi file nello stile di Markdown. Se non hai familiarità con markdown dai un'occhiata al Markdown Cheatsheet. È essenzialmente un modo per contrassegnare il testo (indicare intestazioni, collegamenti, immagini, ecc.) Senza codice HTML.
Se stai creando una sezione con pagine secondarie utilizzando una cartella, puoi specificare le pagine secondarie nello stesso modo di prima. All'interno della cartella creata crea singoli file che iniziano il nome del file con un numero (che dà alla pagina il suo ordine) e il nome che desideri visualizzare.
Un'altra cosa carina Daux.io ti permette di creare una landing page per le tue sezioni. Tutta la documentazione può ottenere una pagina di destinazione se si crea un file "_index.md". Dai un'occhiata all'esempio di default per avere un'idea della formattazione.
Ogni sezione può anche avere una pagina di destinazione. Se una sezione non ha una pagina di destinazione, la voce del menu di livello superiore non esegue il click-through ovunque, si apre semplicemente l'elenco della sotto-sezione. Se desideri che la voce di primo livello abbia una propria pagina, crea un file "index.md" all'interno della cartella per la sezione.
Alcuni progetti potrebbero richiedere più documentazioni. Un sito Web può garantire una documentazione per l'utente finale e una documentazione per lo sviluppatore che contenga informazioni estremamente diverse.
Un modo per gestire più esigenze di documentazione come questo è creare più istanze di Daux.io. Ciò tuttavia richiede di eseguire il server separatamente e di reimpostare alcune cose. Fortunatamente c'è un modo migliore!
Dai un'occhiata al file "global.json" nella cartella della documentazione principale. Se apri questo con il tuo editor di testo dovresti vedere che il docs_directory parametro è impostato su docs. Crea una copia della directory docs, chiamala "user_docs" e aggiungi alcuni file fittizi per poterla distinguere dalla documentazione originale.
Ora cambia il docs_directory parametro a User_Docs e ricarica la documentazione nel tuo browser. Ora stai visualizzando il contenuto della nuova cartella. Ciò semplifica il passaggio da una documentazione all'altra, senza dover riavviare il server o utilizzare un'altra istanza di Daux.io.
Ovviamente alla fine della giornata dobbiamo distribuire la nostra documentazione. Questo è meglio fatto in forma HTML e Daux.io ci ha coperto! Nel terminale, mentre nella directory principale della documentazione eseguire il seguente comando:
php generate.php
Ciò creerà una cartella "statica" con tutti i file HTML e le risorse necessarie per visualizzare la documentazione. Puoi comprimere questa cartella e inviarla a qualcuno o caricarla su un server e collegarla ad essa.
Ci sono un sacco di cose che puoi controllare tramite il file "default.json". Di default ci saranno a Fatto da Todaymade link nella barra laterale insieme ad alcuni link segui su Twitter che non hai bisogno o vuoi personalizzare per il tuo progetto. La pagina principale di Daux.io elenca le opzioni che puoi usare sotto "Configurazione" più in basso nella pagina. o semplicemente fare riferimento al file "default.json".
Puoi usare "twitter": ["yourtwittername"] per esempio aggiungi il tuo link di Twitter. I collegamenti possono essere controllati usando il link parametro, ecco come aggiungere una coppia:
"collegamenti": "GitHub Repo": "https://github.com/yourgithubrepo", "Supporto": "http://support.myproduct.com", "Fatto da me": "http: // mywebsite .com "
Puoi trovare tutte le opzioni sulla pagina principale di Daux.io. Ecco un esempio di un file "default.json" completo per un progetto immaginario.
"title": "My Project", "tagline": "My Stylish Documentation", "docs_directory": "docs", "valid_markdown_extensions": ["md", "markdown"], "repo": "danielpataki / exampleproject "," twitter ": [" danielpataki "]," tema ":" daux-blue "," breadcrumb ": false," template ":" default "," clean_urls ": false," toggle_code ": false," date_modified ": false," float ": false," collegamenti ": " GitHub Repo ":" https://github.com/danielpataki/exampleproject "," Supporto ":" http://support.exampleproject.com ", "Made by Daniel": "http://danielpataki.com"
Configurare Daux.io può sembrare un compito scoraggiante all'inizio, ma non è così lungo, specialmente sui sistemi Mac / Linux in cui la maggior parte di ciò di cui abbiamo bisogno è preinstallato. Se non sei abituato al terminale e ai server locali, ci vorrà un po 'di tempo per abituarsi all'ambiente, ma così facendo pagherai dieci volte tanto.
Una volta che ti alzi con Daux.io, scoprirai che è facile da usare, flessibile e facile da mantenere. Il tuo progetto, il tuo cliente, i tuoi colleghi di lavoro e gli utenti finali del tuo progetto ti ringraziano per i tuoi sforzi e, si spera, il tuo tempo trascorso a sostenere il progetto sarà ridotto al minimo.
Accentsconagua