I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Kenneth, who works at Heroku, kicked off the morning at Write the Docs. He started his talk by stating that, “Constraints foster creativity.” It’s about the simple things: prime lenses, mechanical watches, pen and paper, etc. In his code and documentation he aims for pragmatism and constraints. If you try to build something that works for everyone’s use case it causes a bad experience for all.
With Kenneth’s Requests tool, he took this approach. What makes a code package popular is the API. All other things are secondary. Developers spend hours every day working with your APIs. If you don’t put a high level of craftsmanship in to those products you’ll only be frustrating your most frequent users.
Documentation is what helps your API grow without becoming compromised. Before any code is written, write the README – show some examples. Then, you should write some code with the theoretical code that you’ve just documented.
Kenneth relates this approach to responsive design. A README-driven API design is responsive to the needs and use case of your users.
He quoted Pieter Hintjens who said that, “Simplicity is always better than functionality.”
Documentation is the glue that makes open source projects possible. As Kenneth put it, if you got to a page and don’t know what problem the code solves then the project has failed. Documentation helps you to explain what problem your code is solving.
Technical debt, code inconsistencies, and many other aspects of internal development issues stem from poor documentation. Both open source projects and internal code are essentially useless without documentation.
Documentation, for Kenneth, leads to better code, a better workplace, and a better lifestyle. It allows more asynchronous workflow where coworkers can dive right in to a new code project without needing to bother someone else about how the API works.