Documentation tutorial Documentation Release 0.3.0 Patrick Vergain 2018-5-3 Contents 1 Documentation 3 1.1 Documentation news...........................................3 1.1.1 Documentation news 2018...................................3 1.1.2 Documentation news 2017...................................3 1.1.3 Documentation news 2016...................................4 1.2 Documentation Advices.........................................4 1.2.1 You are what you document (Monday, May 5, 2014).....................5 1.2.2 Rédaction technique......................................5 1.2.3 13 Things People Hate about Your Open Source Docs.....................7 1.2.4 Beautiful docs..........................................7 1.2.5 Designing Great API Docs (11 Jan 2012)...........................7 1.2.6 Docness.............................................7 1.2.7 Hacking distributed (february 2013)..............................7 1.2.8 Jacob Kaplan-Moss (November 10, 2009)...........................8 1.2.9 Agile documentation best practices...............................8 1.2.10 Best Practices for Documenting Technical Procedures Melanie Seibert............8 1.2.11 Plone..............................................8 1.2.12 Twilio..............................................9 1.2.13 Other advices..........................................9 1.3 Documentation generators........................................ 11 1.3.1 Sphinx.............................................. 12 1.3.2 Authorea............................................ 147 1.3.3 Doxygen............................................ 147 1.3.4 Javadoc............................................. 162 1.3.5 Jekyll.............................................. 162 1.3.6 JSDoc.............................................. 163 1.3.7 Mkdocs............................................. 164 1.3.8 Pandoc............................................. 165 1.4 Good documentation........................................... 167 1.4.1 CakePHP............................................ 167 1.4.2 Passlib.............................................. 167 1.4.3 Sfepy.............................................. 167 1.4.4 Shark.............................................. 168 1.5 Formats Documentation......................................... 168 1.5.1 Input formats.......................................... 168 1.5.2 Input/output formats...................................... 178 i 1.5.3 Output formats......................................... 178 1.6 Documentation projects......................................... 182 1.6.1 C Documentation projects................................... 182 1.6.2 Mozilla documentation..................................... 182 1.6.3 Documenting python projects.................................. 182 1.7 Documentation tools........................................... 184 1.7.1 Dash............................................... 184 1.7.2 Graphviz............................................ 185 1.7.3 Zeal documentation browser.................................. 186 1.8 Documentation videos.......................................... 186 1.8.1 Write the docs.......................................... 186 1.8.2 RTFM - wRite The Friendly Manual.............................. 187 1.9 Wiki documentation........................................... 187 1.9.1 Mediawiki............................................ 187 1.9.2 Wiki tools............................................ 198 2 Command Line Interface (CLI) 203 2.1 Introduction............................................... 203 2.2 Usage................................................... 204 2.2.1 CLI and python......................................... 204 2.2.2 CLI with Perl.......................................... 204 2.2.3 Command Line Interface (CLI) on GNU/linux......................... 209 2.2.4 Command Line Interface (CLI) on Windows.......................... 221 2.2.5 Google cli............................................ 233 ii Documentation tutorial Documentation, Release 0.3.0 Documentation tutorial Release 0.3.0 Date 2018-5-3 Authors Patrick Vergain Target Tutorial about documentation See also: • https://gdevops.gitlab.io/tuto_devops/ • genindex • reStructuredText Sphinx documentation • https://gitlab.com/gdevops/tuto_documentation • https://gdevops.gitlab.io/tuto_documentation/index.html • https://devopstutodoc.readthedocs.io/en/latest/index.html • https://readthedocs.org/projects/devopstutodoc/ Contents 1 Documentation tutorial Documentation, Release 0.3.0 2 Contents CHAPTER 1 Documentation See also: • http://blog.smartbear.com/software-quality/bid/256072/13-reasons-your-open-source-docs-make-people-want-to-scream • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html • http://redaction-technique.org/index.html 1.1 Documentation news 1.1.1 Documentation news 2018 Contents • Documentation news 2018 – Bringing interactive examples to MDN Bringing interactive examples to MDN See also: • https://hacks.mozilla.org/2018/03/bringing-interactive-examples-to-mdn/ 1.1.2 Documentation news 2017 3 Documentation tutorial Documentation, Release 0.3.0 Contents • Documentation news 2017 – Autodoc-style extraction into Sphinx for your JS project Autodoc-style extraction into Sphinx for your JS project See also: • sphinx-js : autodoc-style extraction into Sphinx for your JS project 1.1.3 Documentation news 2016 Contents • Documentation news 2016 – La documentation linux utilise sphinx La documentation linux utilise sphinx See also: • https://github.com/return42/linuxdoc • https://return42.github.io/linuxdoc/ • https://lwn.net/Articles/692704/ L’annonce sur https://lwn.net/Articles/692704/ 1.2 Documentation Advices See also: • parse_API_doc • http://producingoss.com/en/getting-started.html • http://justwriteclick.com/book/ • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html • http://redaction-technique.org/index.html Contents • Documentation Advices – You are what you document (Monday, May 5, 2014) – Rédaction technique 4 Chapter 1. Documentation Documentation tutorial Documentation, Release 0.3.0 * Libérez vos informations de leurs silos * Intégrer la documentation aux processus de développement – 13 Things People Hate about Your Open Source Docs – Beautiful docs – Designing Great API Docs (11 Jan 2012) – Docness * Docness Source code – Hacking distributed (february 2013) – Jacob Kaplan-Moss (November 10, 2009) – Agile documentation best practices – Best Practices for Documenting Technical Procedures Melanie Seibert – Plone – Twilio – Other advices 1.2.1 You are what you document (Monday, May 5, 2014) See also: • http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html • http://jacobian.org/writing/great-documentation/ • http://zachholman.com/posts/documentation/ • http://blog.parse.com/2012/01/11/designing-great-api-docs/ • http://www.mikepope.com/blog/DisplayBlog.aspx?permalink=1680 • https://github.com/PharkMillups/beautiful-docs • http://blog.codinghorror.com/if-it-isnt-documented-it-doesnt-exist/ • http://docs.writethedocs.org/writing/beginners-guide-to-docs/ The number one cause of startup failure is not the product, but the distribution: it doesn’t matter how good the product is if no one uses it. With software, the documentation is the distribution: it doesn’t matter how good the code is if no one uses it. If it isn’t documented, it doesn’t exist. 1.2.2 Rédaction technique See also: • http://redaction-technique.org/index.html 1.2. Documentation Advices 5 Documentation tutorial Documentation, Release 0.3.0 Libérez vos informations de leurs silos Des solutions souples et fiables libèrent vos informations des silos d’information cloisonnés où elles sont emprisonnées et sous-exploitées. Oubliez MS Word ou FrameMaker pour passer de la maintenance de la documentation à la gestion du cycle de vie des projets documentaires modulaires ! Intégrer la documentation aux processus de développement La documentation fait partie du logiciel. Fournie avec le produit, elle doit : • sortir en même temps, • suivre les mêmes cycles de vie, et • faire l’objet des mêmes processus de production et de contrôle qualité. Elle doit répondre idéalement aux critères suivants : • pas de vendor lock-in (indépendance du format et de l’éditeur de contenu), • chaînes de publication libres et gratuites, • mise en page totalement automatisée. Il y a quelques années encore, les seuls outils permettant de fournir des livrables de qualité au format PDF ou HTML reposaient sur des formats binaires et propriétaires qui s’intégraient mal aux systèmes de gestion de versions des équipes de développement. Résultat : réalisée à part, la documentation technique répondait difficilement aux mêmes exigences de qualité et de délai de mise sur le marché que les produits. 6 Chapter 1. Documentation Documentation tutorial Documentation, Release 0.3.0 DocBook, puis DITA XML et reStructuredText ont changé la donne : ces formats texte peuvent être modifiés avec tout type de programme, du simple éditeur de texte à l’‘IDE graphique, et s’intègrent parfaitement sous Subversion, Git ou tout autre système de gestion de versions. 1.2.3 13 Things People Hate about Your Open Source Docs See also: • http://blog.smartbear.com/careers/13-things-people-hate-about-your-open-source-docs/ • http://www.framablog.org/index.php/post/2013/06/28/documentation-defauts-open-source 1.2.4 Beautiful docs See also: • https://github.com/PharkMillups/beautiful-docs 1.2.5 Designing Great API Docs (11 Jan 2012) See also: • http://blog.parse.com/2012/01/11/designing-great-api-docs/ 1.2.6