A mild surprise came by in mid January when DigitalOcean had cut their prices. This one was interesting in more ways than one for me. For starters, this meant, double the resources/flexibility where needed. And more than that, more leverage for a case I have been arguing against over the last few weeks (or years) now.
By principle, I advocate adversity as the touchstone, not of character, but efficiency. Something that I learned the hard way, and also got logical inputs on, growing up with things.
Yes, agree that it is not everyone's cup of tea (or coffee, or whatever), but I haven't found it fail. Unless of course, one defines failure as not adhering to Argumentum ad populum.
The test was to see how the DigitalOcean REST API client helped.
As much as it has helped in capacities small and medium, the need for docs made a lot of sense that one night. Firing up a python shell, creating a client, and resizing 15-20 boxes was a piece of cake. Or should I say, a nice cup of coffee?
This in place, I went around pinging people on Twitter to give the client a try; need outsider thoughts after all. As a PM with DO favourited a tweet from me there came a much needed realisation; docs were pathetic. Spent the night rewriting the docs within the code and using Sphinx to generate doc pages.
Since then, a major change has come up with how I tend to write code - Sphinx ready, is the code. Working with another developer whose primary dialect is Python had indeed numbed. The need for keeping documentation well written for an outsider somehow got missed.
With this in mind, and how development practices have changed in the last few months, jotting down. Something for a new developer, or something for an older one who forgot with age.
Write a lot of documentation; both within code, and otherwise. Paper and pencil is my chosen modus but whatever sails your boat, works well.
Do not write without a clear picture; bare-bones architecture and otherwise.
Start with ensuring what you write is easy to build, deploy, and maintain for another poor soul. But, for your own sake and another's don't obsesses about this.
Use Sphinx or another documentation generation tool and ensure your APIs are consumable. After all, your API is as good as the box it resides in, if there are no consumers. And, good consumers, a second pair of eyes that see what you missed, don't come without docs.
Be tad empathetic with a developer, who assuming you go through #4, consumes your APIs. Easier indeed to say they are not smart enough to consume your API, but as I recollected, eventual loss, is yours.
Shy away from shame of your poor/half-baked work. As Reid Hoffman said, is is fine that your first version is embarrassing. Build on the scaffold, and don't stop with embarrassment.
I could be way off here, but take up criticism that comes by with bounds of fairness. As a corollary, shun all that is otherwise. This is a tricky one to deal with, but that's what would make you a better developer/person dealing with another.
Subscribe to As we go passing
Get the latest posts delivered right to your inbox