Below are my slides for the presentation held in PLOG2013 Plone symposium. It’s about good software development documentation culture, writing documentation for Python packages and maintaining up-to-date developer documentation in Plone ecosystem.

(slideshare.net IFRAME above)

1. Transcript

slideshare.net really screwed up this one.

1. Writing the docs Mikko Ohtamaa PLOG / 2013 Sorrento, Italy

2. Agenda The culture of good documentation Documenting Python code Documentation tools in Plone

3. Mikko Ohtamaa moo9000 opensourcehacker.com Open Source 103323677227728078543 Hacker

4. Am I a bad person If I don’t write documentation

5. YES.

6. Peer-driven culture vs. product-driven culture

7. http://blog.gerv.net/2013/03/why-the-smart-people-leav/

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

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

10. Don’t worry ☠

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

12. developer.plone.org ( like stateful readthedocs.org with buildout ) ( like a boss )

13. Consumers of Plone the project are developers

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

15. [ developer.plone.org demo ]

16. Fix your workflow Write code Write code ~ write docs Write tests Write tests Write docs

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

18. [ Github inline edit demo ]

19. Share your slides slideshare.net Link in developer.plone.org

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

21. moo9000 Open Source Hacker opensourcehacker.com 103323677227728078543 Kiitos

 Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+