>Who needs documentation when you have the power of intuition? YOLO-Driven Development encourages you to keep your genius solutions locked away in your head. After all, real developers don’t read documentation; they conjure it from thin air.
Apparently this style of development has already become very popular as almost none of the projects that I look at have any documentation at all.
I'm inclined to say that if you name things obviously and avoid cutesy idioms (AOP/reflection magic, ridiculous object hierarchies, etc) that code can be quite grokkable with little documentation. Of course this falls apart once you start dealing with hundreds of microservices or decades of tech debt but such is life.
It is worse than that. Being good at expressive, self-documenting code correlates with strong communication skills and empathy. So programmers who get good at it tend to increase the risk of managerial borgification.
I know a lot of great coders who ended up doing anything but code because they were the technical people with communication skills.
1. Before writing a class or a function write comments about what the code will do (unless it’s absolutely trivial)
2. Check if the comments make sense
3. Write the code
That simple practice almost guarantees understandable code.
Indeed, the code _itself_ can often be understood from reading the code. Documentation is for everything _else_ - explanation of the choices made and motivations when picking a particular design (so that they can be re-evaluated when a redesign is considered), customer-facing onboarding guides, runbooks for how to carry out operational tasks, and so on.
Documentation in the form of project planning documents, SOWs, data diagrams etc... - that stuff is always quite valuable, especially since it comes with an understanding that it was valid at a certain point in time (and may no longer be valid) but belies underlying decisions in how things were built and why.
If there are 5 parameters, and 3 of them are helped with a bit of context, then adding superfluous comments to the other two makes sense because that in itself is a piece of documentation (parameters needed for a function or class).
If all of your comments are like that though? Gross.
Three years later I can’t say that everybody uses it (I do!), but it has 176 pages in it, from infrastructure to how to run the company to things we learnt on the tech we use. Every time we lose time on a silly bug, we document it there so next time you can save the day with a Ctrl+F. All relevant dev or ops changes are documented here so when you notice some strange pattern in Grafana you can check the log and see that someone updated some config on that day. Every time there’s an incident in production we document how we fixed it.
If tomorrow I leave the company, I know I’ll have very little to write down because everything is already there.
The hard parts are:
* not all people are willing to "waste" time filling the docs. It feels like wasting time but it’s always valuable for your future self as you won’t remember all the things you know today, and when someone joins the company you can point them to the docs instead of spending days explaining stuff
* the more content you have the harder it is to keep it updated. We try to do it but in any case it’s in git so you can check the last commit to know if some content is old or not
* having non-tech people contribute to it. At the beginning they had access to it but were a bit confused by Markdown. Now the marketing docs are in ClickUp (the tasks manager we use). We looked at Notion and similar solutions but for tech people there’s nothing better than a repository cloned on your computer in which you can grep
* when you’re exhausted or frustrated because you spent the day on an issue, it can be hard to motivate yourself to document it. What I do is I keep a file open while I debug an issue and I write down what I do _as I do it_. That way all I have to do at the end is some formatting.
- a guide to the system to orient yourself
- a reference for the api to look up in
- tutorials to teach it
- examples to copy/paste
Each has a different audience and requires a different structure and writing style.
I once spent a project being the lone wolf against my will, writing tons of documentation with diagrams. Didn't matter, if anything it just made the rest feel insecure and look bad. Everyone says they want docs but often they don't, really, because they don't read them when they do exist.
it may be difficult, but sometimes things are difficult
free and open source but private and paid for documentation???
the documentation has the same socialpolitical problem as any other artistic expression encoded into a digital asset
but the code has a subtly different socialpolitical problem that goes a little bit further than the one of 'mere' digital assets.
I don't expect to be understood, I just wrote this to think to myself... albeit in public.