Share
Hva du skal skapeDokumentasjon av et prosjekt kan være en plage, men det trenger ikke å være. Det er ganske mange verktøy der ute for å få jobben gjort - jeg bruker ofte Daux.io på grunn av sin fleksibilitet.
I denne artikkelen vil jeg vise deg hvorfor du bør dokumentere, hvordan du kan få Daux.io og hvordan du kan begynne å bruke den akkurat nå for å gjøre prosjektene dine mye bedre.
Skrive dokumentasjon for prosjektet ditt kan være den viktigste avgjørelsen du gjør. Årsaken til at dette ofte overses for nettbaserte prosjekter er at det ikke er så mye på spill.
Ta en Boeing 787 for eksempel. Dette produktet har en omfattende dokumentasjon som støtter alle aspekter fra design til vedlikehold. Det er til og med en håndbok på nesten 150 sider som dokumenterer 787 egenskaper for å ta hensyn til når du planlegger flyplasser.
Hvorfor skal et fly ha omfattende dokumentasjon mens et nettsted ikke gjør det?
Jeg tror det er tre hovedårsaker:
Nettsteder har sjelden sikkerhetsproblemer, men så snart skala eller penger reagerer på hodet, kan du være sikker på at dokumentasjonen vil dukke opp. Alle store prosjekter som Twitter og Facebook har svimlende mengder informasjon tilgjengelig for utviklere, både internt og tredjepart.
Nettsteder som genererer mye inntekt, velger ofte også å lage god dokumentasjon. Tanken er at hvis noe må endres, kan alle referere til dokumentasjonen, og nettsiden er mye mindre sannsynlig å tape penger på grunn av tap av oppetid.
Betyr dette at du kan få uten dokumentasjon for et mindre prosjekt? Sikker på det, spørsmålet er: skal du?
Dokumentasjon gir en felles referanseramme for et prosjekt. Fordelen med dette er ganske åpenbart når du arbeider i et lag, men det blir oversett når noen jobber alene.
Hvis du lager dine boligbyggingswebsteder, er sjansene at du bygger minst et par år. Kan du huske hvordan et nettsted du bygget i januar automatisk tweets innholdet når du kommer til å se på det neste august? Hva om et selskap ber deg om å overlevere et prosjekt til en annen utvikler? Du kan tilbringe en time hver morgen og svare på spørsmål om koden din for neste måned.
Selv den mest konsistente koderen er inkonsekvent. Når vi vokser og lærer, har vi en tendens til å endre måten vi jobber på. Kanskje du har introdusert et byggverktøy som Gulp i arbeidsflyten din, kanskje du har begynt å bruke objektorientert PHP.
Dokumentasjon kan også forklare situasjoner som ikke er åpenbare i selve koden. Du har kanskje valgt en subparalløsning med vilje, rett og slett fordi du ble bedt om å gjøre noe raskt og slutten rettferdiggjorde midlene. Dette kan legges til dokumentasjonen, kanskje som en oppgave å oppgradere senere.
Daux.io kan skremme noen mennesker først fordi det ikke er bare enkelt HTML, det kan bare forhåndsvises ved hjelp av en server. Men det er ganske enkelt å sette det opp, og når du hopper over det, er bruken lett og fleksibel.
Den enkleste måten å få Daux.io på er å laste den ned fra Github. Du kan laste ned pakken ved hjelp av Last ned ZIP knappen på høyre sidefelt. Hvis du er en erfaren Github-bruker, kan du klone den, eller du kan til og med ta den fra Packagist via komponist.
Hvis du laster ned fra Github, bør du ende opp med en mappe med navnet "daux.io-master".
Gi nytt navn til "dokumentasjon" og flytt det til skrivebordet for klarhetens skyld. Å skrive dokumentasjonen gjør du egentlig ikke trenge hva som helst. Du kan redigere Markdown-filene i en hvilken som helst editor og bruke en kommando for å konvertere alt til HTML for enkel deling. Det er imidlertid best å forhåndsvise vårt arbeid mens vi går, så vi skal gjøre noe for det.
For å forhåndsvise dokumentene trenger vi en server. Heldigvis er alt gitt i Daux.io prosjektmappen, vi trenger bare forutsetningene for å kjøre serveren: npm og Grunt.
Den enkleste måten å få tak i npm (Node Package Manager) er å installere Node. Gå til Node-nettstedet og last ned installasjonsprogrammet. Når installert, bør du kunne bruke kommandoen npm i terminalen (på Linux / OS X) eller i ledeteksten (Windows).
Raskt notat: Jeg vil referere til ledeteksten på Windows og terminalen på Linux / OS X med samme ord: terminal.
Det neste du trenger er Grunt. Grunt er faktisk installert via npm, så hvis du allerede har fullført det siste trinnet, bør det være super enkelt. Åpne terminalen og skriv inn følgende kommando:
npm installere -g grunt-cli
Du har nå grunnverktøyene som trengs for å komme i gang. Hvis du er ny til npm anbefaler jeg sterkt å lære mer om det. Det lar deg enkelt installere verktøy, og du trenger ikke nødvendigvis å vite Node.js for å bruke verktøy som fungerer med npm (som Grunt).
Alt opp til dette punktet er bare nødvendig hvis du ikke allerede har disse verktøyene installert. Uansett hvor mange forekomster av Daux.io-dokumentasjonene du har rundt, trenger du ikke å gjøre dette igjen.
Tips: lære mer om kommandolinjeverktøy ved å følge nybegynnerens serie Kommandolinjen for webdesign av Kezz Bracey.
Dette trinnet er kun for Windows-brukere, OS X og de fleste Linux-distribusjoner leveres med PHP forhåndsinstallert, så hvis du er på disse plattformene, kan du hoppe over denne delen. Dessverre å installere PHP-kommandolinjen i Windows er litt av et problem, her er det nedkjørt.
Gå videre til PHP nedlastingssiden og ta tak i versjonen av PHP du vil. Jeg brukte "VC11 x86 Non Thread Safe" -versjonen når du testet. Jeg lastet ned og hentet dette arkivet til rotmappen min, C: / og omdøpt den resulterende mappen til "php". På slutten av prosessen bør du ha en mappe med navnet "php" i hovedkatalogen din: mappen skal inneholde en "php.exe" et sted.
Deretter må vi sørge for at PHP-kommandoen kan kjøres fra hvor som helst. På Windows 7, den enkleste måten å gjøre dette på er å gå til startmenyen, høyreklikk på Datamaskin og velg Eiendommer. Klikk på Avanserte systeminnstillinger i venstre sidefelt. Klikk på Avansert kategorien, og deretter på Miljøvariabler knappen nederst.
Du må klikke på sti i toppruten og deretter redigere. På slutten av verdien legger du til en mappereferanse, noe som dette: "C: \ Users \ Dani \ environment". Dette bør være en mappe i din egen brukermappe. Når du er ferdig, lagre alt og lag denne mappen. (Hvis du bruker en annen versjon av Windows, ta en titt på Computerhope, viser den hvordan du gjør dette på flere versjoner).
Inne i denne mappen opprett en fil med navnet "phppath.cmd". Rediger denne filen ved hjelp av et tekstredigeringsprogram og legg til følgende innhold:
PATH =% PATH%; C: \ Brukere \ Dani \ miljø php -v
Når du er ferdig, naviger inn i denne mappen via kommandoprompten ved å skrive cd% userprofile% / environment og kjør følgende kommando: phppath.
Til slutt, lukk ledeteksten og åpne den igjen, php skal nå være tilgjengelig globalt. Igjen, dette er noe du bare trenger å gjøre en gang, og bare på Windows.
Fortsett i terminalen din, naviger til prosjektmappen. Husk at dette burde være på skrivebordet vårt på dette stadiet. På Windows kan du bruke følgende kommando for å komme til prosjektmappen:
cd% userprofile% / Desktop / dokumentasjon
På OS X kan du bruke følgende kommando:
cd ~ / skrivebord / dokumentasjon
Den første kommandoen du bør utstede er npm installasjon. En gang det har fullført løp npm oppdatering for å sikre at alt er oppdatert. Disse kommandoene installerer og oppdaterer alle avhengighetene til Daux.io. Du må gjøre dette for hver forekomst av Daux.io du har.
Vi er endelig klar til å forhåndsvise vår dokumentasjon. Dette handler nå om en kommando, alt du trenger å gjøre er å skrive grynte inn i terminalen (sørg for at du er i dokumentasjonsmappen når du utsteder kommandoen).
Etter noen få sekunder å tenke bør du se noe slikt:
Dette betyr at serveren er oppe, kanskje en ny fan allerede har åpnet i nettleseren din. Hvis den ikke har det, ta en titt på IP-adressen som vises ved siden av "Lytte på" i terminalen og skriv inn den i nettleseren din. I mitt eksempel er denne IP'en "127.0.0.1:8085".
Merk: I noen tilfeller åpnes kategorien, men viser "ingen side funnet" eller noen lignende feil. I dette tilfellet legger på tappen etter et par sekunder, kan serveren ha litt mer tid til å initialisere.
Du bør nå se standarddokumentasjonen som er oppgitt i nettleseren. Visningen du ser er generert ad hoc fra dokumentasjonen Markdown-filer. Nå som vi kan se hva vi gjør, la oss se på skriftlig dokumentasjon.
I mappen "dokumentasjon" bør du se en "docs" -mappe. Dette inneholder din faktiske dokumentasjon, alt annet er for Daux.io å gjøre sin magi. Daux.io bruker en bestemt navngivningskonvensjon for å gi deg full kontroll over sidens rekkefølge.
Hvert element på denne siden skal starte med et tall og et understreke. Jo høyere tallet nederst ned på siden er i dokumentasjonen. Hvis du trenger en enkelt side, opprett en Markdown-fil (f.eks .: 04_Updating_Plugins), hvis du trenger en hierarkisk struktur av sider, opprett en mappe (f.eks .: 05_Code_Styling).
Teksten etter nummeret bestemmer navnet på siden i dokumentasjonen. Mine tidligere eksempler blir "Oppdateringsplugger" og "Kodestyling". Pass på at du bare bruker alfanumeriske tegn og understreker, understreker blir konvertert til mellomrom.
Fra nå av er det jevnt seiling, alt du trenger å gjøre er å redigere filene dine i Markdowns stil. Hvis du ikke er kjent med markdown, ta en titt på Markdown Cheatsheet. Det er egentlig en måte å markere tekst på (angi overskrifter, lenker, bilder, etc.) uten HTML-kode.
Hvis du lager en seksjon med undersider med en mappe, kan du angi undersider på samme måte som før. I den opprettede mappen opprettes individuelle filer som starter filnavnet med et nummer (som gir siden sin rekkefølge) og navnet du vil vise.
En annen fin ting Daux.io lar deg gjøre er å lage en destinasjonsside for dine seksjoner. Hele dokumentasjonen din kan få en destinasjonsside hvis du oppretter en "_index.md" -fil. Ta en titt på standardeksemplet for å få en følelse for formateringen.
Hver seksjon kan også ha en destinasjonsside. Hvis en seksjon ikke har en destinasjonsside, klikker menyelementet på toppnivå ikke over til hvor som helst, det åpner bare opp underdelingslisten. Hvis du vil at toppnivåoppføringen skal ha sin egen side, opprett en "index.md" -fil i mappen for delen.
Noen prosjekter kan kreve flere dokumentasjoner. Et nettsted kan garantere en sluttbrukerdokumentasjon og en utvikler dokumentasjon som vil inneholde svært forskjellige opplysninger.
En måte å håndtere flere dokumentasjonsbehov for, slik som dette, er å skape flere forekomster av Daux.io. Dette krever imidlertid at du kjører serveren separat og sett opp noen ting igjen. Heldigvis er det en bedre måte!
Ta en titt på "global.json" -filen i hoveddokumentasjonsmappen. Hvis du åpner dette med tekstredigeringsprogrammet, bør du se at docs_directory parameteren er satt til docs. Opprett en kopi av docs-katalogen, kaller den "user_docs" og legg til noen forskjellige dummyfiler til den for å kunne fortelle den fra den opprinnelige dokumentasjonen.
Endre nå docs_directory parameter til user_docs og last opp dokumentasjonen i nettleseren din. Du ser nå innholdet i den nye mappen. Dette gjør det enkelt å bytte frem og tilbake mellom dokumentasjoner i fly, uten å måtte starte om serveren eller bruke en annen forekomst av Daux.io.
Selvfølgelig på slutten av dagen må vi distribuere vår dokumentasjon. Dette er best gjort i HTML form og Daux.io har oss dekket! I terminalen, mens du er i hoveddokumentasjonen i dokumentasjonen, kjør du følgende kommando:
php generate.php
Dette vil opprette en "statisk" mappe med alle HTML-filene og ressursene som trengs for å se dokumentasjonen. Du kan zip denne mappen opp og sende den til noen eller laste den opp til en server og lenke til den.
Det er en rekke ting du kan styre via "default.json" -filen. Som standard vil det være a Laget av Todaymade lenke i sidefeltet sammen med noen Twitter følge koblinger du heller ikke trenger eller vil tilpasse til prosjektet ditt. Daux.io hovedside viser oppføringene du kan bruke under "Konfigurasjon" lenger ned på siden. eller bare referer til "default.json" -filen.
Du kan bruke "twitter": ["ditt navn"] for å legge til din egen Twitter-kobling for eksempel. Lenker kan styres ved hjelp av lenker parameter, her er hvordan du legger til et par:
"lenker": "GitHub Repo": "https://github.com/yourgithubrepo", "Support": "http://support.myproduct.com", "Laget av meg": "http: // mywebsite .com "
Du finner alle alternativene på Daux.io hovedsiden. Her er et eksempel på en full "default.json" -fil for et imaginært prosjekt.
"title": "My Project", "tagline": "Min stilige dokumentasjon", "docs_directory": "docs", "valid_markdown_extensions": ["md", "markdown"], "repo": "danielpataki / exampleproject "," twitter ": [" danielpataki "]," tema ":" dauxblue "," breadcrumbs ": falsk," mal ":" standard "," clean_urls ": falsk," toggle_code ": false," date_modified ": false," float ": false," links ": " GitHub Repo ":" https://github.com/danielpataki/exampleproject "," Support ":" http://support.exampleproject.com " "Laget av Daniel": "http://danielpataki.com"
Oppsett av Daux.io kan se ut som en skremmende oppgave først, men det er ikke så lang, spesielt på Mac / Linux-systemer der det meste av det vi trenger er forhåndsinstallert. Hvis du ikke er vant til terminalen og lokale servere, kan det ta litt tid å bli vant til miljøet, men det vil betale seg ti ganger.
Når du er ferdig med Daux.io, finner du at den er enkel å bruke, fleksibel og enkel å vedlikeholde. Ditt prosjekt, din klient, dine medarbeidere og prosjektets sluttbrukere vil alle takke for din innsats, og forhåpentligvis vil tiden du bruker for å støtte prosjektet bli minimert.
Accentsconagua