Why documentation osidays


Published on

The most hated thing a developer can imagine is writing documentation. But on the other hand nothing can compare with a well sorted documentation, in case you want to change or extend something or just want to get into the topic again. We all know, there is no major way how to do documentation, but there a number of principles and todos which makes it much easier for you. This talk is not about tools, like phpDocumentor, nor is it about promoting a special way of documentation. It is about some of the thoughts you should have gone through, before and when writing documentation.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Why documentation osidays

  1. 1. So, I shall document?!Bastian Feder OSIDays 2011, Bangalorebastian.feder@liip.ch 21st November 2011
  2. 2. What is documentation?„Documentation is an informative text used as referenceto a special aspect or topic. Its goal is it to make thedocumented objects findable, searchable andunderstandable. Documentationis not limited todocuments, but also images, movie strips, or elsefollowing the named cause.To archieve this normally documentation languages orcontrolled vocabularities are used.“
  3. 3. What is documentation? It makes informationen available to reading, search, and filtering. Can be of text, imagery, or moving images Has its own languages with rules and vocabulary.
  4. 4. Why is documentationnecessary? Shortens the introduction of new team members or expats Increases the clarity of the project. Decreases the error level when extending your software
  5. 5. What prevents us fromdocumenting? Time pressure Incapability to express thoughts No or too less knowledge of the used documentation language If done faithfully, it might get expesive Short term projects („It is replaced soon, any way“)
  6. 6. To the rescue Coding Guidelines API- Documentation Wiki for extended documentation about the architecture and/or single modules auf your software.
  7. 7. Coding Guidelines Help you to keep your sources clean Contain a rule set for API-Documentation Can be verified manual (CodeSniffer) automatical (e.g. SVN precommit-Hook und CodeSniffer or your IDE)
  8. 8. API-Documentation Supported by many IDEs Get extract by static code analysers like phpDox Many output formats are supported by different helpers Consistant output
  9. 9. Wiki Format is supported by some IDEs (at least the Media- Wiki format) Easy to keep up to date Increases correctness due to more than one person might get access Revisioning (if supported) Export mechanisms to several formts (PDF, Doc, Markup, etc.)
  10. 10. Proposal for documentation Top 1 Interfaces has to be documented extensively. List all parameters, the return values, and its types and boundaries
  11. 11. Proposal for documentation Top 2 No generation of documentation; this can only be a listing of classes, members, methods, and namespaces. Even a description how something works is better.
  12. 12. Proposal for documentation Top 4 Complex code will not be understood without a significant amount of work if not documented, even by the author.
  13. 13. conclusion Undocumented code is a significant burdon for each developer Undocumented code causes the necessity to reverse engineering. Undocumented code will cause unnecessery workload
  14. 14. Discussion
  15. 15. PHP5.3 Powerworkshop New features of PHP5.3 Best Pratices using OOP PHPUnit PHPDocumentor
  16. 16. License  This set of slides and the source code included in the download package is licensed under theCreative Commons Attribution-Noncommercial-Share Alike 2.0 Generic License http://creativecommons.org/licenses/by-nc-sa/2.0/deed.en