This presentation was held in PLOG2013, Sorrento, Italy. It's about good software development documentation culture, writing documentation for Python packages and maintaining up-to-date developer documentation in Plone ecosystem.

1. Writing the docs
Mikko Ohtamaa PLOG / 2013
Sorrento, Italy
Friday, April 5, 13

2. Agenda
The culture of good
documentation
Documenting Python code
Documentation tools in Plone
Friday, April 5, 13

3. Mikko Ohtamaa gk
nr
io
kw
o
or
Lo
f
moo9000 opensourcehacker.com
Open Source
103323677227728078543
Hacker
Friday, April 5, 13

4. Am I a bad person If I
don’t write
documentation?
Friday, April 5, 13

5. YES.
Friday, April 5, 13

6. Peer-driven culture vs.
product-driven culture
Friday, April 5, 13

7. http://blog.gerv.net/2013/03/why-the-smart-people-leav/
Friday, April 5, 13

8. Arch of Doom
&
i ty Outsourcing
lar ess
pu in companies start “German breakfast time”
Po app using your product
h
e
Tim
Story begins with happy peers
Friday, April 5, 13

9. “No gaps, no questions
needed”
documentation is
necessary for the
project to scale
Friday, April 5, 13

10. Don’t worry ☠
Friday, April 5, 13

11. How to doc Python
README.rst (PyPi, Github, .egg)
Sphinx
Autodoc
readthedocs.org, pythonhosted.org
Well-commented unit tests
Friday, April 5, 13

12. developer.plone.org
( like stateful readthedocs.org with buildout )
( like a boss )
Friday, April 5, 13

13. Consumers of Plone
the project are
developers
Friday, April 5, 13

14. d.p.org ingredients
Body of knowledge
Tutorials
External package documentation
Graveyard of old documentation
bil ity
sco vera
Di
Friday, April 5, 13

15. [ developer.plone.org
demo ]
Friday, April 5, 13

16. Fix your workflow
Write code Write code ~ write docs
Write tests Write tests
Write docs
Friday, April 5, 13

17. Low-hanging fruits
For every blog post you
write link it
For every
stackoverflow.com d.p.org
question you make link
it
For every IRC answer
you receive write it ust
down tio n m
nfo rma uts ide
I st o head
exi ur
yo
Friday, April 5, 13

18. [ Github inline edit
demo ]
Friday, April 5, 13

19. Share your slides
slideshare.net
Link in developer.plone.org
Friday, April 5, 13

20. Top-of-the-shelf bottles
Theming tutorial
Development
friendliness out of
the box
Making Plone itself
more dev friendly
Friday, April 5, 13

21. moo9000
Open Source Hacker
opensourcehacker.com
103323677227728078543
Kiitos
Friday, April 5, 13