Share
Ce que vous allez créerLa documentation d'un projet peut être une nuisance, mais ce n'est pas nécessaire. Il existe assez peu d'outils pour faire le travail - j'utilise souvent Daux.io en raison de sa flexibilité.
Dans cet article, je vais vous montrer pourquoi vous devriez documenter, comment obtenir Daux.io et commencer à l'utiliser dès maintenant pour améliorer vos projets..
Écrire la documentation de votre projet pourrait être la décision la plus importante que vous preniez. La raison pour laquelle cela est souvent négligé pour les projets basés sur le Web est qu’il n’ya pas grand-chose en jeu..
Prenez un Boeing 787 par exemple. Ce produit dispose d'une documentation complète sauvegardant tous les aspects, de la conception à la maintenance. Il existe même un manuel de près de 150 pages documentant les caractéristiques du 787 à prendre en compte lors de la planification des aéroports..
Pourquoi un avion devrait-il avoir une documentation étendue alors qu'un site Web ne le fait pas??
Je crois qu'il y a trois raisons principales:
Les sites Web ont rarement des problèmes de sécurité, mais dès que des économies d'échelle ou d'argent apparaissent, vous pouvez être sûr que de la documentation apparaîtra. Tous les grands projets tels que Twitter et Facebook disposent d'une quantité incroyable d'informations disponibles pour les développeurs, qu'ils soient internes ou externes..
Les sites Web générant beaucoup de revenus choisissent souvent de créer une bonne documentation. L'idée est que si quelque chose doit être modifié, tout le monde peut se référer à la documentation et le site Web est beaucoup moins susceptible de perdre de l'argent en raison d'une perte de disponibilité.
Est-ce que cela signifie que vous pouvez vous en sortir sans documentation pour un projet plus petit? Bien sûr, la question est: devriez-vous?
La documentation fournit un cadre de référence commun pour un projet. L'avantage de cela est assez évident quand on travaille en équipe, mais on l'oublie quand quelqu'un travaille seul.
Si vous construisez votre vie en construisant des sites Web, il est probable que vous en construisiez au moins quelques années. Vous souviendrez-vous du fait qu'un site Web que vous avez créé en janvier tweete automatiquement son contenu lorsque vous le consultez en août prochain? Et si une entreprise vous demande de confier un projet à un autre développeur? Vous passerez peut-être une heure chaque matin à répondre aux questions sur votre code pour le mois prochain..
Même le codeur le plus cohérent est incohérent. En grandissant et en apprenant, nous avons tendance à modifier notre façon de travailler. Peut-être avez-vous introduit un outil de construction comme Gulp dans votre flux de travail, peut-être avez-vous commencé à utiliser PHP orienté objet.
La documentation peut également expliquer des situations qui ne sont pas évidentes dans le code lui-même. Vous avez peut-être choisi exprès une solution médiocre, simplement parce qu'on vous a demandé de faire quelque chose rapidement et que la fin justifiait les moyens. Cela peut être ajouté à la documentation, peut-être comme tâche de mise à niveau ultérieure.
Daux.io peut effrayer certaines personnes au début, car il ne s’agit pas que du simple HTML, il ne peut être prévisualisé que sur un serveur. Cependant, la configuration est assez simple et une fois que vous avez franchi cet obstacle, l'utilisation est simple et flexible..
Le moyen le plus simple d’obtenir Daux.io est de le télécharger à partir de Github. Vous pouvez télécharger le package en utilisant le Télécharger le ZIP bouton sur la barre latérale droite. Si vous êtes un utilisateur expérimenté de Github, vous pouvez le cloner, ou même le récupérer depuis Packagist via Composer.
Si vous téléchargez depuis Github, vous devriez vous retrouver avec un dossier nommé "daux.io-master".
Renommez-le en «documentation» et déplacez-le sur votre bureau pour plus de clarté. Pour écrire votre documentation, vous ne le faites pas avoir besoin n'importe quoi. Vous pouvez éditer les fichiers Markdown dans n’importe quel éditeur et utiliser une commande pour tout convertir en HTML afin de faciliter le partage. Cependant, il est préférable de prévisualiser notre travail au fur et à mesure, nous allons donc nous préparer à cela..
Pour avoir un aperçu de la documentation, nous aurons besoin d’un serveur. Heureusement, tout est fourni dans le dossier du projet Daux.io. Nous avons juste besoin des pré-requis pour exécuter le serveur: npm et Grunt..
Le moyen le plus simple de récupérer npm (Node Package Manager) est d’installer Node. Accédez au site Web du nœud et téléchargez le programme d'installation. Une fois installé, vous devriez pouvoir utiliser la commande npm dans le terminal (sous Linux / OS X) ou dans l'invite de commande (Windows)..
Note rapide: Je ferai référence à l'invite de commande sous Windows et au terminal sous Linux / OS X avec le même mot: Terminal.
La prochaine chose dont vous aurez besoin est Grunt. Grunt est en fait installé via npm, donc si vous avez déjà terminé la dernière étape, cela devrait être super simple. Ouvrez le terminal et tapez la commande suivante:
npm installer -g grunt-cli
Vous avez maintenant les outils de base nécessaires pour commencer. Si vous êtes nouveau sur npm, je vous recommande vivement d’en apprendre plus à ce sujet. Il vous permet d'installer facilement des outils et vous n'avez pas nécessairement besoin de connaître Node.js pour utiliser les outils qui fonctionnent avec npm (comme Grunt)..
Jusqu'ici, tout n'est nécessaire que si ces outils ne sont pas déjà installés. Peu importe le nombre de cas de documentations Daux.io que vous avez autour de vous, vous n'aurez plus à le refaire.
Pointe: En savoir plus sur les outils de ligne de commande en suivant la série pour débutants La ligne de commande pour la conception Web de Kezz Bracey.
Cette étape s’adresse uniquement aux utilisateurs Windows, à OS X et à la plupart des distributions Linux livrées avec PHP pré-installé. Par conséquent, si vous utilisez ces plates-formes, vous pouvez ignorer cette section. Malheureusement, l'installation de la ligne de commande PHP dans Windows est un peu fastidieuse, voici la description finale.
Rendez-vous sur la page des téléchargements PHP et récupérez la version de PHP que vous souhaitez. J'ai utilisé la version «VC11 x86 Non Thread Safe» lors des tests. J'ai téléchargé et extrait cette archive dans mon dossier racine, C: / et ai renommé le dossier résultant en «php». À la fin du processus, vous devriez avoir un dossier nommé “php” dans votre répertoire principal C: /, ce dossier devrait contenir un “php.exe” quelque part..
Ensuite, nous devrons nous assurer que la commande PHP peut être exécutée n'importe où. Sous Windows 7, le moyen le plus simple consiste à accéder au menu Démarrer, à cliquer avec le bouton droit de la souris sur Ordinateur et sélectionnez Propriétés. Cliquer sur Réglages avancés du système dans la barre latérale gauche. Clique sur le Avancée onglet, puis sur le Variables d'environnement bouton en bas.
Vous devrez cliquer sur chemin dans le volet supérieur puis modifier. A la toute fin de la valeur, ajoutez une référence de dossier, comme ceci: “C: \ Users \ Dani \ environment”. Cela devrait être un dossier dans votre propre dossier utilisateur. Une fois cela fait, sauvegardez tout et créez ce dossier. (Si vous utilisez une version différente de Windows, regardez Computerhope, il explique comment procéder pour plusieurs versions.).
Dans ce dossier, créez un fichier nommé «phppath.cmd». Editez ce fichier en utilisant n’importe quel éditeur de texte et ajoutez le contenu suivant:
PATH =% PATH%; C: \ Utilisateurs \ Dani \ environnement php -v
Une fois cela fait, naviguez dans ce dossier via l'invite de commande en tapant cd% userprofile% / environment et lancez la commande suivante: phppath.
Enfin, fermez l’invite de commande et rouvrez-la, php devrait maintenant être disponible globalement. Encore une fois, c’est quelque chose que vous ne devez faire qu’une fois, et uniquement sous Windows..
Toujours dans votre terminal, accédez au dossier du projet. Rappelez-vous que cela devrait être sur notre bureau à ce stade. Sous Windows, vous pouvez utiliser la commande suivante pour accéder au dossier du projet:
cd% userprofile% / Desktop / documentation
Sous OS X, vous pouvez utiliser la commande suivante:
cd ~ / Desktop / documentation
La première commande à exécuter est npm installer. Une fois que cela est terminé npm update pour s'assurer que tout est à jour. Ces commandes installent et mettent à jour toutes les dépendances de Daux.io. Vous devrez le faire pour chaque instance de Daux.io que vous avez.
Nous sommes enfin prêts à prévisualiser notre documentation. C’est maintenant une question de commande, tout ce que vous avez à faire est de taper grognement dans le terminal (assurez-vous que vous vous trouvez dans le dossier de documentation lors de l'exécution de la commande).
Après quelques secondes de réflexion, vous devriez voir quelque chose comme ceci:
Cela signifie que le serveur est opérationnel et qu'un nouvel onglet est peut-être déjà ouvert dans votre navigateur. Si ce n'est pas le cas, examinez l'adresse IP affichée à côté de «Listening on» dans le terminal et entrez-la dans votre navigateur. Dans mon exemple, cette adresse IP est «127.0.0.1:8085».
Remarque: dans certains cas, l'onglet s'ouvre mais indique “Aucune page trouvée” ou une erreur similaire. Dans ce cas, rechargez l'onglet après quelques secondes, le serveur peut avoir besoin d'un peu plus de temps pour s'initialiser..
Vous devriez maintenant voir la documentation par défaut fournie dans le navigateur. La vue que vous voyez est générée ad-hoc à partir des fichiers de la documentation Markdown. Maintenant que nous pouvons voir ce que nous faisons, examinons la rédaction de documentation.
Dans le dossier «documentation», vous devriez voir un dossier «docs». Cela contient votre documentation actuelle, tout le reste appartient à Daux.io pour faire sa magie. Daux.io utilise une convention de nommage spécifique pour vous donner un contrôle total sur l'ordre des pages..
Chaque élément de cette page doit commencer par un chiffre et un trait de soulignement. Plus le chiffre est élevé, plus la page sera basse dans la documentation. Si vous avez besoin d'une seule page, créez un fichier Markdown (par exemple: 04_Updating_Plugins), si vous avez besoin d'une structure hiérarchique de pages, créez un dossier (par exemple: 05_Code_Styling)..
Le texte après le numéro détermine le nom de la page dans la documentation. Mes exemples précédents deviendront “Updating Plugins” et “Code Styling”. Veillez à n'utiliser que des caractères et des soulignements alfanumériques, les soulignements seront convertis en espaces.
A partir de maintenant, la navigation est fluide, tout ce que vous avez à faire est de modifier vos fichiers dans le style de Markdown. Si vous n'êtes pas familier avec Markdown, jetez un coup d'œil à la feuille de notes de Markdown. C'est essentiellement un moyen de baliser du texte (indiquer des titres, des liens, des images, etc.) sans code HTML.
Si vous créez une section avec des sous-pages utilisant un dossier, vous pouvez spécifier des sous-pages de la même manière qu'auparavant. Dans le dossier créé, créez des fichiers individuels en commençant le nom de fichier par un numéro (qui donne son ordre à la page) et en indiquant le nom de votre choix..
Une autre chose intéressante que Daux.io vous permet de faire est de créer une page de renvoi pour vos sections. Toute votre documentation peut obtenir une page de destination si vous créez un fichier "_index.md". Regardez l'exemple par défaut pour avoir une idée de la mise en forme.
Chaque section peut également avoir une page de destination. Si une section n'a pas de page d'arrivée, l'élément de menu de niveau supérieur ne permet pas de cliquer n'importe où, il ouvre simplement la liste des sous-sections. Si vous souhaitez que l'entrée de niveau supérieur ait sa propre page, créez un fichier «index.md» dans le dossier de la section..
Certains projets peuvent nécessiter plusieurs documentations. Un site Web peut garantir une documentation pour l'utilisateur final et une documentation pour développeurs contenant des informations extrêmement différentes..
Une façon de gérer plusieurs besoins de documentation tels que celui-ci consiste à créer plusieurs instances de Daux.io. Cela nécessite toutefois que vous exécutiez le serveur séparément et que vous configuriez à nouveau certaines tâches. Heureusement, il y a un meilleur moyen!
Consultez le fichier «global.json» dans le dossier principal de la documentation. Si vous ouvrez ceci avec votre éditeur de texte, vous devriez voir que le répertoire_docs paramètre est défini sur docs. Créez une copie du répertoire docs, nommez-la «user_docs» et ajoutez-y différents fichiers factices pour pouvoir le distinguer de la documentation d'origine..
Maintenant changer le répertoire_docs paramètre à user_docs et rechargez la documentation dans votre navigateur. Vous visualisez maintenant le contenu du nouveau dossier. Cela facilite le basculement entre les documentations à la volée, sans avoir à redémarrer le serveur ni à utiliser une instance différente de Daux.io..
Bien sûr, en fin de compte, nous devons distribuer notre documentation. Ceci est mieux fait sous forme HTML et Daux.io nous a couverts! Dans le terminal, dans le répertoire principal de votre documentation, exécutez la commande suivante:
php generate.php
Cela créera un dossier «statique» avec tous les fichiers HTML et ressources nécessaires pour afficher la documentation. Vous pouvez compresser ce dossier et l'envoyer à quelqu'un ou le télécharger sur un serveur et y accéder..
Il y a beaucoup de choses que vous pouvez contrôler via le fichier "default.json". Par défaut, il y aura un Fabriqué par Todaymade lien dans la barre latérale avec certains liens de suivi Twitter que vous n'avez pas besoin ou que vous souhaitez personnaliser pour votre projet. La page principale de Daux.io répertorie les options que vous pouvez utiliser sous «Configuration» plus bas dans la page. ou simplement vous référer au fichier “default.json”.
Vous pouvez utiliser "twitter": ["yourtwittername"] pour ajouter votre propre lien Twitter par exemple. Les liens peuvent être contrôlés en utilisant le liens paramètre, voici comment ajouter un couple:
"links": "GitHub Repo": "https://github.com/yourgithubrepo", "Support": "http://support.myproduct.com", "Made by Me": "http: // site web .com "
Vous trouverez toutes les options sur la page principale de Daux.io. Voici un exemple de fichier "default.json" complet pour un projet imaginaire.
"titre": "Mon projet", "slogan": "Ma documentation élégante", "répertoire_docs": "docs", "valid_markdown_extensions": ["md", "markdown"], "repo": "danielpataki / exampleproject "," twitter ": [" danielpataki "]," theme ":" daux-blue "," breadcrumbs ": false," template ":" default "," clean_urls ": false," code_change ": false," date_modified ": false," float ": false," links ": " GitHub Repo ":" https://github.com/danielpataki/exampleproject "," Support ":" http://support.exampleproject.com ", "Fabriqué par Daniel": "http://danielpataki.com"
Configurer Daux.io peut sembler une tâche ardue au début, mais ce n’est pas si long, en particulier sur les systèmes Mac / Linux où la majeure partie de ce dont nous avons besoin est préinstallée. Si vous n’êtes pas habitué au terminal et aux serveurs locaux, cela peut prendre un peu de temps pour s’habituer à l’environnement, mais cela vous rapportera 10 fois plus.
Une fois que vous aurez démarré avec Daux.io, vous constaterez qu’il est facile à utiliser, flexible et facile à entretenir. Votre projet, votre client, vos collègues et les utilisateurs finaux de votre projet vous remercieront tous pour vos efforts et espérons que votre temps passé à soutenir le projet sera réduit au minimum..
Accentsconagua