>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.
Some problem domains are inherently complex and the code written for them needs documentation. Some are not but get complicated during the design process and perverted into abominations that wouldn't have required documentation if the design and source were more readable.
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.
> code can be quite grokkable with little documentation
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.
This is quite true and one of the reasons I hate auto-doc comments. If a function tells me that an input is an integer there's no reason to repeat that information in the header above the function unless that information is then being parsed to produce a more readable form of documentation (i.e. as JavaDoc was originally used). Additionally I personally, though I am happy to concede that it may benefit some people, loathe "$documentId The ID of a Document" style comments. If you are adding more information above and beyond what is relevant from code - especially if that information relates to why you chose this approach over a different one - that is useful information.
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.
The only justification I can give to “$documentId - The ID of a document” style comments would be if they are alongside comments that actually give context.
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.
That’s the theory. In real life, code is written by teams with different levels of skills over multiple periods of time. Expressiveness is a really hard skill that take years to master and that few people have and that you can only learn by yourself.
> Expressiveness is a really hard skill that take years to master
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.
In general, they tend to get snapped up by other corporate roles, either officially (which at least grants them the pay benefits associated with the role) or unofficially.
I know a lot of great coders who ended up doing anything but code because they were the technical people with communication skills.
When there's a complex bit of code, I expect to be able to `git blame` lookup the githash on GitHub and read the PR/issue description that should say what it's trying to achieve and how. I write PR descriptions expecting them to help years later.
I started a new job at a small company 3 years ago and the very first thing I did was to create a central documentation repository, using Jekyll for some "fancy" rendering. All you have to do is dump your knowledge in a markdown file. There’s no hard convention; the goal is to have no barrier for entry.
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.
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.
At most companies the consensus is that if you want to understand the product, you need to master the code. Which can suck for legacy code that doesn't follow sane conventions.
Honestly, this is the way most early stage startups operate, other than this one:
> 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.
Yeah true, scope creep is generally a bad one for startups.
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.
This feels like an amazing bit of scissor-writing. I don't know the real percentages, but yeah, half of y'all will immediately recognize this is satire and the other half will immediately recognize this as the best working philosophy ever.
Gotta go fast. Somewhere out there a competitor is eating your lunch. Now is better than later. Later is better than never. Avoid anything that slows you down: thinking, testing, fixing bugs, writing code.
Yeah, for all the garbage codebases that are difficult to maintain there's an entire graveyard of projects that got stuck in analysis paralysis and never got past the hello world phase.
I'm having too much fun imagining a project starting with a single `main.c` with nothing but `printf("Hello, world!\n");` back in 2010 with the project being stalled by endless enterprise architecture meetings.
The problem is that when your codebase is garbage enough, after a couple of years you inevitably get stuck in analysis paralysis because nobody understands how to make changes to the system in a way that doesn't break everything.
I have never quite understood YOLO as it is used. Why would I do something especially risky while realizing I only live once? If I had 10 lives, I would take many risks, but since I only live once, I will try to make a reasonable balance between risk and reward.
It is picking the adventure over playing it safe. "You only live once so you just as well pick the once in a lifetime, most exciting, or whatever experience." What an author finds exciting and YOLOs may be above your risk tolerance.
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...)"
I understand that if I only live once I don't want to waste the time I have on things that I don't enjoy. I don't understand when it means rushing into something that could cause immediate catastrophic failure.
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.
Pragmatically, you will try to optimize the balance.
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.
I know there's a giant "/s" at the end of that, but omg I am on vacation at the moment reading random HN while I wait for Rimworld to load, and this is too true.
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.
Interested in learn more about those tools.
> 4. Duct Tape and WD-40 Are Your Allies
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.
Contractors and YOLO code have an interesting relationship. A lot of near-shore contractors are folks who are extremely strong developers... but the main motivation for writing clean code (for non-junior developers) is that you'll need to return to that code in a few weeks months or years - and you've been burned by your own poorly written code in the past. This motivation doesn't really exist for contractors - write once code that does what it says on the tin (no matter how horrific it is internally) will get you your payday.
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.
Absent the part about sprints, this describes the majority of professional software development that I've been a part of. Not all of it, but most.
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.
Prototyping can be a great way to explore the solution space. Just make sure to learn as many lessons as possible and then burn the prototype with fire.
Startups almost by definition face a literal deadline. They critically depend on people who code 80h per week instead of partying.
The impact of UI changes can be hard to measure. If the deployment platforms are very heterogeneous, it's literally impossible to test all scenarios. In these cases it makes sense to roll out slowly and find ways to measure the impact. Or to limit the fallout.
Sometimes, simple solutions get the job done perfectly well and run for years with manageable upkeep. It's a slippery slope though.
It can be very difficult to capture the domain knowledge and the insight of developers and operations people in documentation. Documenting will bog them down instead of getting things done. Managing the bus factor and training up people ahead of time is crucial.
I find it hard to believe that the most successful startups are the ones who code 80h per week unless you guarantee that the output of the code is big $$$
You have to convince your stakeholders that further investment is worth it. But I also think that the "go big or go home" strategy comes from seriously messed-up incentives. It might be justified if the margin is very low or if aquiring a big user base for other purposes is the actual goal.
Probably not what the parent poster was talking about, but fear is a great inhibitor. Excessively high standards for documentation and depth of scope might inhibit less experienced engineers, and nitpicking about scope is a pointless waste of time that ends up being a managerial excuse for more meetings especially if it's brought up endlessly when the core feature does not yet work. This promotes a culture of fear which can paralyze a team of engineers and all you end up getting out of them is the bare minimum.
The “move fast and break things” context. Ship it now, make butt load of money by over promising and under delivering. No need for testing or docs. Adding half baked features, you only live once.
You can tell this is satire by the fact that it is a manifesto, it is a literary form only used by the other side, we yolo'er don't have time for those. There is a lot of nuance to breaking rules but most people can't think for themselves so they just shouldn't do that. Sort of like the saying the psychotic drawn in the water in which in mystic swim.
>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.