PyGrunn: Documentation is king - Kenneth Reitz¶

Tags: pygrunn, python

(One of the summaries of the one-day 2014 PyGrunn conference in Groningen in the Netherlands).

Note: Kenneth Reitz gave another talk earlier during the day called “growing open source seeds”. I was at a different talk, but the title is the same as a talk he gave at last year’s EU djangocon. And I do have a summary of that one. A good talk!

Note 2: can’t get enough? He also compared Django and Flask at the 2013 EU djangocon. Recommended, mainly because of his suggestion to use open source all the things as your software architecture. “It is a helpful mindset to at least treat everything you make like it will be open sourced, even if you won’t actually do it.”

Anyway, on to his actual talk about documentation!

He found a trend in all the stuff he does: the best things are simpler. For instance: prime lenses, handheld games, pen and paper, mechanical watch, a single carry-on bag. Constraints foster creativity. So something that constrains helps you get creative. Kenneth needs simple things to function well.

The most well-known Python thing he’s build is the requests library. Nice and simple and waaaaay more useful than the default python httplib.

Developers spend more than 8 hours a day with an API. They ought to be good! There’s a Steve Jobs quote from 1983 about computers needing a lot of design because you spend more than 3 hours a day on them. Three hours is more time than you spend in cars and cars get a lot of design spend on their interface. So: spend time on your API and make it simple.

How do you keep your API good and simple? By writing the docs first. Before any code is written, write the README. Instead of coding a bit to get the job done, you first figure out the problem and actually sove it. You need to work with the problem, discover the problem, to get a good solution. Same with responsive design. It is about making something that identifies itself enough to respond to the environment it’s placed in.

Simple code is good. Small sharp, distributed services. There’s a quote he likes: simplicity is always better than functionality.

Open source is epic. Part of social changes. Building block of social media. Big. Important. There are many bad examples of open source. There are also great open source projects. If you look at the difference between them: often the differentiator is documentation. Communicating your intent. Communicating how to work with it. Communicating the core idea.

Look at internal company code. Some patterns: components are tightly coupled; it is hardly documented; you need a brain-dump of the core engineer in order to work on it.

The alternative: pretent the internal project is open source. This is what automatically happens:

• Components become concise and decoupled.

• Concerns separate themselves.

• Best practices emerge (so: no DB credentials in your code).

• Documentation and tests become crucial.

• Code can be released at any time.

All good things! And only because you’re treating it as open source.

Documentation means better code. Documentation is more important than tests. Documentation forces you to think about your code from the users’ perspective. It steers your development. It helps you get your API right. If you really having to explain something in depth, you naturally notice inconsistencies.

Documentation also means a better workplace. Every design decision should be documented. It helps with bringing new devs on-board. Employees can hop from project to project. And documentation is the starting point for automation. You cannot have automation without good documentation.

It also gives you a better live: asynchronous development, you won’t be interrupted that much by co-workers. Everyone can stay up to speed much more when there’s good documentation.

Documentation also improves the world :-)