Writing the docs

2,134 views

Published on

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.

Published in: Technology
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,134
On SlideShare
0
From Embeds
0
Number of Embeds
988
Actions
Shares
0
Downloads
3
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide

Writing the docs

  1. 1. Writing the docs Mikko Ohtamaa PLOG / 2013 Sorrento, ItalyFriday, April 5, 13
  2. 2. Agenda The culture of good documentation Documenting Python code Documentation tools in PloneFriday, April 5, 13
  3. 3. Mikko Ohtamaa gk nr io kw o or Lo f moo9000 opensourcehacker.com Open Source 103323677227728078543 HackerFriday, April 5, 13
  4. 4. Am I a bad person If I don’t write documentation?Friday, April 5, 13
  5. 5. YES.Friday, April 5, 13
  6. 6. Peer-driven culture vs. product-driven cultureFriday, April 5, 13
  7. 7. http://blog.gerv.net/2013/03/why-the-smart-people-leav/Friday, April 5, 13
  8. 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 peersFriday, April 5, 13
  9. 9. “No gaps, no questions needed” documentation is necessary for the project to scaleFriday, April 5, 13
  10. 10. Don’t worry ☠Friday, April 5, 13
  11. 11. How to doc Python README.rst (PyPi, Github, .egg) Sphinx Autodoc readthedocs.org, pythonhosted.org Well-commented unit testsFriday, April 5, 13
  12. 12. developer.plone.org ( like stateful readthedocs.org with buildout ) ( like a boss )Friday, April 5, 13
  13. 13. Consumers of Plone the project are developersFriday, April 5, 13
  14. 14. d.p.org ingredients Body of knowledge Tutorials External package documentation Graveyard of old documentation bil ity sco vera DiFriday, April 5, 13
  15. 15. [ developer.plone.org demo ]Friday, April 5, 13
  16. 16. Fix your workflow Write code Write code ~ write docs Write tests Write tests Write docsFriday, April 5, 13
  17. 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 yoFriday, April 5, 13
  18. 18. [ Github inline edit demo ]Friday, April 5, 13
  19. 19. Share your slides slideshare.net Link in developer.plone.orgFriday, April 5, 13
  20. 20. Top-of-the-shelf bottles Theming tutorial Development friendliness out of the box Making Plone itself more dev friendlyFriday, April 5, 13
  21. 21. moo9000 Open Source Hacker opensourcehacker.com 103323677227728078543 KiitosFriday, April 5, 13

×