Comment by makeitdouble
16 days ago
> "Oops, sorry, didn't get around to documenting it".
That's obviously the wrong message. They should say "Go ask the engineering VP to get us off any other projects for another cycle while we're writing 'satisfying' documentation".
Extensive documentation comes at a price few companies are willing to pay (and that's not just a matter of resources. Look at Apple's documentation)
I write documentation as I'm writing the code. In my opinion, the code is only as good as its documentation -- they're two parts of the same thing. It's mostly comments at the top of files, and sometimes a markdown file in the same directory.
This way, good documentation is priced into my estimate for the project. I don't have a work item "spend a few days documenting." Nope, if I'm doing a foo then that includes documenting a foo at the same time.
> the code is only as good as its documentation
This heavily depends on your niche I think. If you're writing closed source vendor software and your client's only guiding light is your documentation, it's 100% true.
If you're working on a 5 people project that evolves at a fast pace, and everyone touching the code is expected to be familiar with the domain and operations, you'll mostly leave comments (todos, meta info, external ticket links etc), not documentation per se.
Everywhere I've worked, there is software written by those five people, who are now all rich and don't write code anymore, and I still would appreciate the courtesy of an explainer.
The trouble with good docs is that they are work to maintain, like good code. If we decide to change this component in a substantial way soon, which we likely will, I'd have to practically rewrite the docs! Why bother?
Because the docs are part of the code. Write the docs.
I don't expect to win this crusade, but I'll keep writing docs anyway. Then later people will modify the code without modifying the docs, and so the docs will be a lie, but still useful, I think.
It's like asking three people who are not closely familiar with a component, but who have worked with it, "what is this thing, how does it work?" You will get three different answers. It would be nice if one of them were a written description straight from the horse's mouth, even if the component is now more of a camel.
Documenting what is there usually is not the hard part (and AI is getting pretty good at that part btw).
Documenting how to use or interact with it in a specific context, which often includes perspectives on interactions with other components, or e.g. protocols not explicit in the code, deciding where to draw the lines of what can assumed trivial common knowledge and what should be specified or explicitly not specified without notices not to rely on these etc. , that is a different thing.
If it wasn't, then truly as they used to say, the source code would be it's own best documentation (I am a big fan of programming for readability, but even the best readable code, while it will be correct and up to date, will never be enough nor the best for all)
In my experience, coding is much faster when doing it this way.
Yes, you can produce a small amount of code faster if you don’t “waste” your time on documentation, but that becomes counterproductive as soon as you can no longer keep the entire codebase in your head.
With documentation one of the major hurdles is the maintainance. It is caring for a set of documents, created by people with different specializations, that describe the artefact from specific perspectives, but need to be kept in sync with the active creation and evolution of the artefact itself.
This is not impossible, but the effort and costs required are substantial and often lose out on a priority basis to just fixing or improving the product itself.
To clarify for me: Is this good or bad?
It's bad. Apple's documentation is notoriously weak, despite them being one of the most well-resourced companies in the world.
Don't worry they're writing documentation now for AI agents
1 reply →