>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.
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.
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???
For this article it's "Life is short so I'm going to favor doing the things I enjoy (releasing something at "it works!", add a feature because it sounds fun, wear socks that don't match) and not the things I don't enjoy (documentation, tests, collaborating/compromising with others...)"
In this case it is You Only Launch Once. If I can launch 50 times, I might skip a test since I can just launch again with a fix. If I only get one launch, I am sure as heck going to test it a few times over.
But throwing out YOLO is merely arguing against "no risk", and regardless of how long you stay alive, never really living. A modern take on "No risk, no reward" with a focus on adventure.
> 2. All Nighters over All Sprints
(and some early stage startups operate that way too)
These practices are all bad as a company scales - you need tests to prevent regressions as the code base grows, documentation to avoid repeating yourself, product managers making informed product decisions, etc. But when you have just a handful of employees, and a handful of customers, and are trying to rapidly find product market fit before your angel round runs out, YOLO-Driven Development is where it’s at.
But everything else is fine. Just talk to users too.
I have had a few great experiences where I’ve travelled to a customer with a few other dev/product ppl, and for a few days we just iterate on features that have unclear scope, synching up with them for feedback once or twice per day. But it really only works because we’re right there with the customer, getting constant feedback, and the work is timeboxed instead of scopeboxed.
For more normal cases, where you have to actually ship to get feedback, having a small, fixed scope for the work before you start is much better.
Right before I left, I was getting paged at 7pm on Friday because of a brand new service pushed. Service didn't even start at first, because its image couldn't even be fetched… on Friday. At 7p.
… it's the joke hour(s) of deployments. But at the very least, as an SRE, it'd be appreciated to see at least a mad scramble to claim the page out of a feeling of embarrassment from having just paged the on-call at 7pm¹. But … no … inevitably the only people who do that are the same ones who avoid the 7p deploy…
¹… we used to have a "if you just deployed → you're now on-call for the next 15 min" automation. Miss that automation.
I've met highly skilled contractors that have produced extremely maintainable code and I've met extremely fast working contractors that have fulfilled the contract and left a pile of spaghetti code in their wake.
There are two sides to the coin of #1. At a certain point, you just have to dive into the problem to actually understand the true nature of it. Some programmers will over-plan things and end up astonished when they actually start coding and find a bunch of edge cases nobody thought of, possibly making those weeks of pontification a waste. I've also witnessed what I think of as "fake planning" where lots of people are roped into a task they really don't need to be a part of, and lots of time is spent verbalizing the problem while providing nebulous solutions. In such cases, someone has to have enough responsibility to start coding and bring others in when necessary, rather than having everyone spend weeks talking up a bunch of waffle so that everything is "perfect" by the time you start writing code.
I can actually forgive many of the points of the article, at least in part. #3, #4, and #5 are usually caused either by inexperience or by the business forcing its developers to take shortcuts. I'm not saying I like them, as programmers should avoid using hacks, late testing, and scope creep if they have the ability to. Often times, they don't because of the very system they're working under.
The most egregious YOLO development practice on that list is "#6 - No Documentation, No Problem". It boggles my mind how many developers give such little of a shit about the value of others' time and for others to be able to use the code they're writing. This is a big problem I'm dealing with right now, actually. The problem compounds when you give your software team so much to do that they basically don't have enough time to write comprehensive or practical documentation. What makes matters even worse are the teams that think "the code should be the documentation", also known as "my shit doesn't stink." This attitude is one of my biggest pet peeves because adopters will actually scold you from writing inline documentation describing the intent of a function that is otherwise very algorithmic by necessity. What the actual F??? And then these same people ping me when they don't understand my code. It's like, you'd already know the intent of my function if you allowed my inline documentation to pass through code review.
And no, API documentation in the form of some statically generated site (which someone has to manage and will inevitably be out of date) is not the solution. The problem isn't that we don't know what arguments a class is expecting. All of that is either solved by IDE hints and possibly having been the one to write the thing in the first place. Your fancy autogenerated API docs tell me little of anything I don't already know.
I want documentation, written in the style of a normal human being, that tells me how to get the project up and running and why certain things work the way they do. Is that really too much to ask? Hell, at this point, I don't even care if it's written by an AI. I just want it to exist, to not be woefully out of date, and to act like a source of truth. Don't scatter documentation across inline comments, Github issues, Jira epics, Confluence pages, Google docs, etc. I'm not searching through all that crap when I want to know why a function loops over a bunch of stuff for a reason that isn't obvious, or why we have a concept called "shadow models".
Kill "comments make the code hard to read" with a fire. If you don't want to read comments, then use an IDE that can collapse all the comments at once.
This will almost ensure that code and comments get out of sync!
Complex problems require ingenious solutions. In YOLO-Driven Development, you’ll master the art of duct-tape programming and WD-40 debugging. Your codebase will be a monument to human ingenuity, even if it’s held together with virtual spit and glue.
So far I've seen and tested quite a few development methodologies, including a few flavors of Agile, and I've yet to be convinced of their usefulness.
We've been building software for more than half a century, but I think that the true nature of the beast is still not entirely understood.
