| Authors: | Kenneth Reitz |
|---|---|
| Time: | Monday, 9:00 |
| Session: | http://docs.writethedocs.org/en/2013/conference/talks.html#kenneth-reitz |
| Link: |
Kenneth works for Heroku, and most people know him from the work he’s done. There are about 18 serious projects on github, and 100+ silly experiments. Particularly Requests and the OSX-GCC installer. Other interests: street photography, synthesizers, travel, speaking, gaming. And he’s noticed a trend as he thinks about his favorite (best) things: prime lenses, monophonic synths, pen and paper, mechanical watch. These all have constraints, and constraints foster creativity. The best things are often the simple things [for Kenneth].
This is a pragmatic approach: dealing with things “sensibly and realistically in a way that is based on practical rather than theoretical considerations”. Another way to put this is that if you make 90% of the uses easy, instead of shooting for 100%, you’ll focus on the right things.
With Requests, it’s successful because the API makes 90% of the uses straight-forward. The API is king, and Kenneth thinks it’s been successful due solely to the API. Kenneth solved a real problem for himself, and that resulted in something others could use.
The API is good because Kenneth started with docs: before any code was written, Kenneth wrote a README with hypothetical examples [“coding by wishful thinking”]. Instead of engineering something to get the job done, you interact with the problem itself and build an interface that responds to it. Great sculptures aren’t engineering – they’re discovered. The sculptor studies the marble, he responds to it, and shapes the marble accordingly.
Readme-driving development is “Responsive API Design”.
“Simplicity is always better than functionality.” – Pietr ...
“Open Source” isn’t just about the license, it’s about the distributed, decentralized groups of engineers working together to build an entire ecosystem. And it’s driven by documentation.
Kenneth mentions “bad” projects that appear unmaintained. They fail to solve a clear problem, and have unclear expectations.
“Good” projects solve a clear problem, communicate well with users, and manage expectations realistically. All of these things are documentation.
[I’m ambivalent about this part of the talk... it seems like it’s drifting a bit and “naming names”.]
Internal code bases are often tightly couples and require broad tribal knowledge. Iterative change of components is difficult and technical debt has a tendancy to spread. And these can be a result of little to no documentation. If you pretend that your internal project is open source, that’s going to inform the way you approach it. You’ll write documentation, you’ll avoid putting credentials into code, and tests become crucial. And the code can be released at any time.
Documentation leads to better code. It’s more important that tests. Explaining problems to other developers helps clarify purpose and uncover asymetry. Documentation leads to a better workplace.
Write the docs, or the sloth will find you.