5. Documentation
Why?
Not all code is obvious. Complex code is
complex.
Business rules may be readable, but don’t
explain why they are there.
Finding details takes a long time...it wastes
money to keep re-finding these details
Wednesday, October 23, 13
6. Documentation
Why?
Dependencies between systems may not be
obvious
Helps keep your project in scope (maybe) :)
Not everyone is thinking in the same context
at the same time.
Wednesday, October 23, 13
8. Documentation
Where?
In a wiki?
What happens when code changes?
What if you need to support multiple
versions?
Self hosted, self managed process (script
that rebuilds documentation)
Wednesday, October 23, 13
9. Documentation
“Readability is a primary focus for Python
developers, in both project and code
documentation.”
- Kenneth Reitz, The Hitchhiker's Guide to
Python (python-guide)
“Documentation is communication”
- Jacob Kaplan-Moss, pycon-2011-writinggreat-documentation
Wednesday, October 23, 13
10. ReadTheDocs
Free(!!) hosting for Open Source documentation
Created by Eric Holscher, Charles Leifer, and
Bobby Grace for the 2010 Django Dash
Goals:
It was created to make hosting documentation
simple!
To create a central platform for people to find
documentation (search)
Wednesday, October 23, 13