Share
Wat je gaat creërenHet documenteren van een project kan lastig zijn, maar het hoeft niet zo te zijn. Er zijn nogal wat tools om de klus te klaren - ik gebruik vaak Daux.io vanwege zijn flexibiliteit.
In dit artikel laat ik je zien waarom je moet documenteren, hoe je Daux.io kunt krijgen en hoe je het nu kunt gebruiken om je projecten veel beter te maken.
Het schrijven van documentatie voor uw project kan de belangrijkste beslissing zijn die u neemt. De reden dat dit vaak over het hoofd wordt gezien voor web-gebaseerde projecten is dat er niet zoveel op het spel staat.
Neem bijvoorbeeld een Boeing 787. Dit product heeft een uitgebreide hoeveelheid documentatie die elk aspect van ontwerp tot onderhoud ondersteunt. Er is zelfs een handleiding voor bijna 150 pagina's die de 787 kenmerken documenteert waarmee rekening moet worden gehouden bij het plannen van luchthavens.
Waarom zou een vliegtuig uitgebreide documentatie moeten hebben terwijl een website dat niet doet?
Ik geloof dat er drie belangrijke redenen zijn:
Websites hebben zelden zorgen over de veiligheid, maar zodra schaal of geld de kop opsteekt, weet u zeker dat de documentatie zal verschijnen. Alle grote projecten zoals Twitter en Facebook hebben ontzagwekkende hoeveelheden informatie beschikbaar voor ontwikkelaars, zowel intern als extern.
Websites die veel inkomsten genereren, kiezen er vaak ook voor om goede documentatie te maken. Het idee is dat als er iets moet worden gewijzigd, iedereen naar de documentatie kan verwijzen en dat de website veel minder snel geld verliest door verlies van uptime.
Betekent dit dat je zonder documentatie voor een kleiner project kunt rondkomen? Natuurlijk, de vraag is: zou jij dat moeten doen?
Documentatie biedt een gemeenschappelijk referentiekader voor een project. Het voordeel hiervan is vrij duidelijk wanneer je in een team werkt, maar het wordt over het hoofd gezien wanneer iemand alleen werkt.
Als u uw brood verdient met het bouwen van websites, is de kans groot dat u er minstens een paar per jaar bouwt. Kun je je herinneren hoe een website die je in januari hebt gebouwd, automatisch de inhoud van de website tweeboodt wanneer je hem in augustus wilt bekijken? Wat als een bedrijf je vraagt om een project aan een andere ontwikkelaar over te dragen? Mogelijk brengt u elke ochtend een uur door met het beantwoorden van vragen over uw code voor de volgende maand.
Zelfs de meest consistente coder is inconsistent. Naarmate we groeien en leren, hebben we de neiging om de manier waarop we werken te veranderen. Misschien heb je een build-tool zoals Gulp geïntroduceerd in je workflow, misschien ben je begonnen met het gebruiken van object georiënteerde PHP.
Documentatie kan ook situaties verklaren die niet vanzelfsprekend zijn in de code zelf. Misschien hebt u bewust een sub-pari-oplossing gekozen, simpelweg omdat u werd gevraagd iets snel te doen en het doel de middelen ten goede kwam. Dit kan aan de documentatie worden toegevoegd, misschien als een taak om later te upgraden.
Daux.io kan aanvankelijk sommige mensen afschrikken, omdat het niet alleen eenvoudige HTML is, maar alleen kan worden bekeken met een server. Het is echter vrij eenvoudig om alles in te stellen en als je eenmaal die hindernis hebt genomen, is het gebruik gemakkelijk en flexibel.
De gemakkelijkste manier om Daux.io te krijgen is om het te downloaden van Github. U kunt het pakket downloaden met behulp van de ZIP downloaden knop op de rechterzijbalk. Als je een ervaren Github-gebruiker bent, kun je deze klonen of je kunt hem zelfs via componist pakken via Packagist.
Als je download van Github zou je eindigen met een map genaamd "daux.io-master".
Hernoem dit naar "documentatie" en verplaats het naar je bureaublad voor de duidelijkheid. Om je documentatie te schrijven doe je dat eigenlijk niet nodig hebben iets. U kunt de Markdown-bestanden bewerken in elke editor en een opdracht gebruiken om alles naar HTML te converteren om ze eenvoudig te kunnen delen. Het is echter het beste om een voorbeeld van ons werk te bekijken terwijl we verder gaan, dus we zullen ons daarop voorbereiden.
Voor een voorbeeld van de documenten hebben we een server nodig. Gelukkig zit alles in de Daux.io-projectmap, we hebben alleen de vereisten nodig om de server te draaien: npm en Grunt.
De gemakkelijkste manier om npm te pakken (Node Package Manager) is om Node te installeren. Ga naar de knooppuntwebsite en download het installatieprogramma. Na de installatie zou u de opdracht npm in de terminal (onder Linux / OS X) of in de opdrachtprompt (Windows) moeten kunnen gebruiken.
Snelle notitie: Ik zal verwijzen naar de opdrachtprompt op Windows en de terminal op Linux / OS X met hetzelfde woord: terminal.
Het volgende dat je nodig hebt is Grunt. Grunt wordt feitelijk via npm geïnstalleerd, dus als je de laatste stap al hebt voltooid, zou het supereenvoudig moeten zijn. Open de terminal en typ de volgende opdracht:
npm install -g grunt-cli
U hebt nu de basishulpmiddelen die u nodig hebt om te beginnen. Als je nieuw bent bij npm, raad ik je ten zeerste aan er meer over te leren. Hiermee kunt u eenvoudig tools installeren en hoeft u Node.js niet per se te kennen om tools te gebruiken die met npm werken (zoals Grunt).
Alles tot dit punt is alleen nodig als je deze tools nog niet hebt geïnstalleerd. Ongeacht hoeveel exemplaren van Daux.io-documenten u heeft, u hoeft dit niet nog een keer te doen.
Tip: lees meer over command line-tools door de beginnersreeks The Command Line for Web Design van Kezz Bracey te volgen.
Deze stap is alleen voor Windows-gebruikers, OS X en de meeste Linux-distributies worden geleverd met PHP vooraf geïnstalleerd, dus als u op die platforms zit, kunt u dit gedeelte overslaan. Helaas is het installeren van de PHP-commandoregel in Windows een beetje een gedoe, hier is de run down.
Ga naar de PHP-downloadpagina en pak de versie van PHP die je zou willen hebben. Ik heb de versie "VC11 x86 Non Thread Safe" gebruikt tijdens het testen. Ik heb dit archief gedownload en geëxtraheerd naar mijn hoofdmap, C: / en de resulterende map hernoemd naar "php". Aan het einde van het proces zou je een map genaamd "php" in je hoofddirectory C: / moeten hebben, de map zou ergens een "php.exe" moeten bevatten.
Vervolgens moeten we ervoor zorgen dat de PHP-opdracht overal kan worden uitgevoerd. Op Windows 7, is de eenvoudigste manier om dit te doen om naar het startmenu te gaan, rechtsklik op Computer en selecteer eigenschappen. Klik op Geavanceerde systeeminstellingen in de linkerzijbalk. Klik op de gevorderd tab en vervolgens op de Omgevingsvariabelen knop onderaan.
U moet op klikken pad in het bovenste deelvenster en vervolgens Bewerk. Aan het einde van de waarde voegt u een mapverwijzing toe, iets als dit: "C: \ Users \ Dani \ environment". Dit zou een map moeten zijn in uw eigen gebruikersmap. Eenmaal klaar, slaat u alles op en maakt u deze map. (Als u een andere versie van Windows gebruikt, neem dan een kijkje op Computerhope, het geeft een overzicht van hoe dit in meerdere versies moet worden gedaan).
Maak binnen deze map een bestand met de naam "phppath.cmd". Bewerk dit bestand met een willekeurige teksteditor en voeg de volgende inhoud toe:
PATH =% PATH%; C: \ Users \ Dani \ environment php -v
Eens gedaan, navigeert u in deze map via de opdrachtprompt door te typen cd% gebruikersprofiel% / omgeving en voer de volgende opdracht uit: phppath.
Sluit ten slotte de opdrachtprompt en open deze opnieuw. PHP zou nu wereldwijd beschikbaar moeten zijn. Nogmaals, dit is iets dat je maar één keer hoeft te doen, en alleen in Windows.
Navigeer nog steeds in je terminal naar de projectmap. Houd er rekening mee dat dit in dit stadium op onze desktop moet staan. In Windows kunt u de volgende opdracht gebruiken om naar de projectmap te gaan:
cd% gebruikersprofiel% / Desktop / documentatie
Op OS X kunt u de volgende opdracht gebruiken:
cd ~ / Desktop / documentatie
Het eerste commando dat je zou moeten geven is npm installeren. Als dat is voltooid, wordt het uitgevoerd npm update om ervoor te zorgen dat alles up-to-date is. Deze commando's installeren en updaten alle afhankelijkheden van Daux.io. U moet dit doen voor elk exemplaar van Daux.io dat u heeft.
We zijn eindelijk klaar om onze documentatie te bekijken. Dit is nu een kwestie van één commando, alles wat je hoeft te doen is typen knorren in de terminal (zorg ervoor dat u zich in de documentatiemap bevindt bij het verstrekken van de opdracht).
Na een paar seconden na te denken zou je zoiets als dit moeten zien:
Dit betekent dat de server actief is, een nieuw tabblad is mogelijk al in uw browser geopend. Als dit niet het geval is, kijk dan naar het IP-adres dat wordt weergegeven naast 'Luisteren aan' in de terminal en voer dit in uw browser in. In mijn voorbeeld is dit IP "127.0.0.1:8085".
Notitie: in sommige gevallen wordt het tabblad geopend maar wordt "Geen pagina gevonden" of een soortgelijke fout weergegeven. Laad het tabblad in dit geval na enkele seconden opnieuw, de server heeft mogelijk iets meer tijd nodig om te initialiseren.
U zou nu de standaarddocumentatie in de browser moeten zien. De weergave die u te zien krijgt, wordt ad hoc gegenereerd uit de Markdown-bestanden met documentatie. Nu we kunnen zien wat we doen, laten we kijken naar het schrijven van documentatie.
In de map "documentation" zou u een map "docs" moeten zien. Dit bevat je eigenlijke documentatie, al het andere is voor Daux.io om zijn magie te doen. Daux.io gebruikt een specifieke naamgevingsconventie om u volledige controle over de volgorde van de pagina's te geven.
Elk item op deze pagina moet beginnen met een cijfer en een onderstrepingsteken. Hoe hoger het nummer, hoe lager de pagina in de documentatie. Als u een enkele pagina nodig hebt, maakt u een Markdown-bestand (bijvoorbeeld: 04_Updating_Plugins), als u een hiërarchische structuur van pagina's nodig heeft, maakt u een map aan (bijv .: 05_Code_Styling).
De tekst achter het nummer bepaalt de naam van de pagina in de documentatie. Mijn vorige voorbeelden worden "Update Plugins" en "Code Styling". Gebruik alleen alfanumerieke tekens en underscores, underscores worden geconverteerd naar spaties.
Vanaf hier is het een vlotte vaart, alles wat je hoeft te doen is je bestanden bewerken in de stijl van Markdown. Als u niet bekend bent met markdown, bekijk dan de Markdown Cheatsheet. Het is in wezen een manier om tekst (koppen, links, afbeeldingen, etc.) aan te duiden zonder HTML-code.
Als u een sectie maakt met subpagina's die een map gebruiken, kunt u subpagina's op dezelfde manier als voorheen opgeven. Maak binnen de aangemaakte map afzonderlijke bestanden die de bestandsnaam beginnen met een nummer (dat de pagina zijn volgorde geeft) en de naam die u wilt weergeven.
Nog een ander voordeel van Daux.io is dat u een bestemmingspagina voor uw secties maakt. Uw hele documentatie kan een bestemmingspagina krijgen als u een bestand "_index.md" maakt. Bekijk het standaardvoorbeeld om een gevoel te krijgen voor de opmaak.
Elke sectie kan ook een bestemmingspagina hebben. Als een sectie geen bestemmingspagina heeft, klikt het menu-item op het hoogste niveau niet ergens doorheen, maar wordt de subtitelslijst geopend. Als u wilt dat de vermelding op het hoogste niveau een eigen pagina heeft, maakt u een "index.md" -bestand in de map voor de sectie.
Sommige projecten vereisen mogelijk meerdere documenten. Een website kan een documentatie voor de eindgebruiker en een ontwikkelaarsdocumentatie vereisen die heel andere informatie zou bevatten.
Een manier om meerdere documentatiebehoeften zoals deze te beheren, is door meerdere exemplaren van Daux.io te maken. Dit vereist echter dat u de server afzonderlijk uitvoert en sommige zaken opnieuw opstelt. Gelukkig is er een betere manier!
Bekijk het bestand "global.json" in de hoofddocumentatiemap. Als je dit opent met je teksteditor zou je moeten zien dat het docs_directory parameter is ingesteld op docs. Maak een kopie van de map met documenten, noem deze "user_docs" en voeg er verschillende dummy-bestanden aan toe om het te kunnen onderscheiden van de originele documentatie.
Verander nu het docs_directory parameter naar User_Docs en laad de documentatie opnieuw in uw browser. U bekijkt nu de inhoud van de nieuwe map. Dit maakt het gemakkelijk om heen en weer te schakelen tussen documentaties, zonder de server opnieuw op te starten of een ander exemplaar van Daux.io te gebruiken..
Uiteraard moeten we aan het eind van de dag onze documentatie verspreiden. Dit kunt u het beste doen in HTML-vorm en Daux.io heeft ons gedekt! Gebruik de volgende opdracht in de terminal in de hoofddirectory van uw documentatie:
php genereren.php
Hiermee wordt een "statische" map gemaakt met alle HTML-bestanden en -items die nodig zijn om de documentatie te bekijken. U kunt deze map opzoeken en naar iemand verzenden of deze uploaden naar een server en ernaar linken.
Er zijn een heleboel dingen die je kunt regelen via het bestand "default.json". Standaard is er een Gemaakt door Todaymade link in de zijbalk samen met wat Twitter volgen links die je niet nodig hebt of die je aan je project wilt aanpassen. Op de hoofdpagina van Daux.io staan de opties die u kunt gebruiken onder "Configuratie" verderop op de pagina. of verwijs gewoon naar het bestand "default.json".
Je kunt gebruiken "twitter": ["uwtwitternaam"] om bijvoorbeeld je eigen Twitter-link toe te voegen. Links kunnen worden beheerd met behulp van de koppelingen parameter, hier is hoe u een paar toevoegt:
"links": "GitHub Repo": "https://github.com/yourgithubrepo", "Support": "http://support.myproduct.com", "Made by Me": "http: // mywebsite .com "
U vindt alle opties op de hoofdpagina van Daux.io. Hier is een voorbeeld van een volledig "default.json" -bestand voor een denkbeeldig project.
"titel": "Mijn project", "slogan": "My Stylish Documentation", "docs_directory": "docs", "valid_markdown_extensions": ["md", "markdown"], "repo": "danielpataki / exampleproject "," twitter ": [" danielpataki "]," theme ":" daux-blue "," breadcrumbs ": false," template ":" default "," clean_urls ": false," toggle_code ": false," date_modified ": false," float ": false," links ": " GitHub Repo ":" https://github.com/danielpataki/exampleproject "," Support ":" http://support.exampleproject.com ", "Gemaakt door Daniel": "http://danielpataki.com"
Het opzetten van Daux.io lijkt in eerste instantie misschien een ontmoedigende taak, maar het is niet zo lang, vooral op Mac / Linux-systemen waar het meeste van wat we nodig hebben, vooraf is geïnstalleerd. Als u niet gewend bent aan de terminal en de lokale servers, kan het even duren voordat u gewend bent aan de omgeving, maar dat werkt tien keer zo snel.
Zodra u met Daux.io aan de slag gaat, zult u merken dat het gemakkelijk te gebruiken, flexibel en gemakkelijk te onderhouden is. Uw project, uw klant, uw collega's en de eindgebruikers van uw project zullen u allen bedanken voor uw inspanningen en hopelijk zal uw tijd besteed aan het ondersteunen van het project worden geminimaliseerd.
Accentsconagua