Writing the docsMikko Ohtamaa PLOG / 2013

Sorrento, Italy

Friday, April 5, 13

Agenda

The culture of good documentation

Documenting Python code

Documentation tools in Plone

Friday, April 5, 13

Mikko Ohtamaa

Looking

for work

opensourcehacker.com

Open Source Hacker

103323677227728078543

moo9000

Friday, April 5, 13

Am I a bad person If I don’t write

documentation?

Friday, April 5, 13

YES.

Friday, April 5, 13

Peer-driven culture vs. product-driven culture

Friday, April 5, 13

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

Arch of Doom

Story begins with happy peers

Outsourcingcompanies start

using your product“German breakfast time”Populari

ty &

happiness

Time

Friday, April 5, 13

“No gaps, no questions needed”

documentation is necessary for the project to scale

Friday, April 5, 13

Don’t worry ☠Friday, April 5, 13

How to doc Python

README.rst (PyPi, Github, .egg)

Sphinx

Autodoc

readthedocs.org, pythonhosted.org

Well-commented unit tests

Friday, April 5, 13

developer.plone.org

( like stateful readthedocs.org with buildout )

( like a boss )

Friday, April 5, 13

Consumers of Plone the project are

developersFriday, April 5, 13

d.p.org ingredients

Body of knowledge

Tutorials

External package documentation

Graveyard of old documentation

Discover

ability

Friday, April 5, 13

[ developer.plone.org demo ]

Friday, April 5, 13

Write code

Write tests

Write docs

Write code ~ write docs

Write tests

Fix your workflow

Friday, April 5, 13

Low-hanging fruits

For every blog post you write link it

For every stackoverflow.com question you make link it

For every IRC answer you receive write it down

d.p.org

Informat

ion must

exist ou

tside

your hea

d

Friday, April 5, 13

[ Github inline edit demo ]

Friday, April 5, 13

Share your slides

slideshare.net

Link in developer.plone.org

Friday, April 5, 13

Top-of-the-shelf bottles

Theming tutorial

Development friendliness out of the box

Making Plone itself more dev friendly

Friday, April 5, 13

Kiitos

opensourcehacker.com

Open Source Hacker

103323677227728078543

moo9000

Friday, April 5, 13