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.

1. So, I shall document?!
Bastian Feder OSIDays 2011, Bangalore
bastian.feder@liip.ch 21st November 2011

2. What is documentation?
„Documentation is an informative text used as reference
to a special aspect or topic. Its goal is it to make the
documented objects findable, searchable and
understandable. Documentationis not limited to
documents, but also images, movie strips, or else
following the named cause.
To archieve this normally documentation languages or
controlled vocabularities are used.“

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. Why is documentation
necessary?
Shortens the introduction of new team members or
expats
Increases the clarity of the project.
Decreases the error level when extending your
software

5. What prevents us from
documenting?
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. To the rescue
Coding Guidelines
API- Documentation
Wiki for extended documentation about the
architecture and/or single modules auf your software.

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. 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. 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. Proposal for documentation
Top 1
Interfaces has to be documented
extensively.
List all parameters, the return
values, and its types and
boundaries

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. 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. 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. Discussion

15. PHP5.3 Powerworkshop
New features of PHP5.3
Best Pratices using OOP
PHPUnit
PHPDocumentor

16. License

This set of slides and the source code included
in the download package is licensed under the
Creative Commons Attribution-Noncommercial-Share
Alike 2.0 Generic License
http://creativecommons.org/licenses/by-nc-sa/2.0/deed.en