.. index:: pair: Documentation; Beautiful pair: Documentation; Advices pair: Documentation; Principles pair: Documentation; Mindshare pair: API; Docs .. _documentation_advices: ======================= Documentation Advices ======================= .. seealso:: - 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:: :depth: 3 You are what you document (Monday, May 5, 2014) ================================================ .. seealso:: - 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. Rédaction technique ==================== .. seealso:: - http://redaction-technique.org/index.html 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é. .. figure:: integration-doc-dev.png :align: center 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. **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. .. _reStructuredText: https://pvergain.gitlab.io/pvbookmarks/documentation/doc_generators/sphinx/rest_sphinx/rest_sphinx.html#rest-sphinx 13 Things People Hate about Your Open Source Docs ================================================= .. seealso:: - 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 Beautiful docs ============== .. seealso:: - https://github.com/PharkMillups/beautiful-docs .. _advice_parse_api_doc: Designing Great API Docs (11 Jan 2012) ====================================== .. seealso:: - http://blog.parse.com/2012/01/11/designing-great-api-docs/ Docness ======= .. seealso:: - http://docness.readthedocs.org/ - http://docness.readthedocs.org/en/latest/documentation-is-part-of-product.html Consider the documentation as a component of your product, i.e. don’t package it as an external product or as an option. In software development, your “product” is usually made of the software, which itself is usually based on source code. Docness Source code ------------------- .. seealso:: https://github.com/benoitbryon/docness Hacking distributed (february 2013) ==================================== .. seealso:: - http://hackingdistributed.com/2013/02/11/principled-documentation/ In the beginning, there was no documentation. These days, infrastructure software has terrible documentation. **Take heed of these commandments, for, among hackers, judgment day is every day**. Jacob Kaplan-Moss (November 10, 2009) ===================================== .. seealso:: http://jacobian.org/writing/great-documentation/what-to-write/ Agile documentation best practices ================================== .. seealso:: - http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm - http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm#sthash.nuUKabMJ.dpuf Ideally, an agile document is just barely good enough, or just barely sufficient, for the situation at hand. Documentation is an important part of agile software development projects, but unlike traditionalists who often see documentation as a risk reduction strategy, agilists typically see documentation as a strategy which increases overall project risk and therefore strive to be as efficient as possible when it comes to documentation. Agilists write documentation when that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing **static documentation**. This article summarizes common "best practices" which agilists have adopted with respect to documentation. Best practices for increasing the agility of documentation: Writing Prefer executable specifications over static documents Document stable concepts, not speculative ideas Generate system documentation Simplification Keep documentation just simple enough, but not too simple Write the fewest documents with least overlap Put the information in the most appropriate place Display information publicly Determining What to Document Document with a purpose Focus on the needs of the actual customers(s) of the document The customer determines sufficiency Determining When to Document Iterate, iterate, iterate Find better ways to communicate Start with models you actually keep current Update only when it hurts General Treat documentation like a requirement Require people to justify documentation requests Recognize that you need some documentation Get someone with writing experience Best Practices for Documenting Technical Procedures Melanie Seibert =================================================================== .. seealso:: - http://fr.slideshare.net/MelanieSeibert/best-practices-for-documenting-technical-procedures Plone ===== .. seealso:: - http://opensourcehacker.com/2012/01/08/readthedocs-org-github-edit-backlink-and-short-history-of-plone-documentation/ Twilio ====== .. seealso:: - http://twilio.com/engineering/2012/01/18/dont-skimp-on-documentation - http://readthedocs.org/docs/twilio-python/en/latest/index.html Other advices ============== .. toctree:: :maxdepth: 3 write_the_docs/write_the_docs mindshare