2 ms·
I should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make i
by wpietri 10y ago
I should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make it unnecessary, b) grown to despise useless or out of date docs, which is the bulk of what I see, and c) grown very tired of writing documentation that people end up not reading.
> [...] plain English is always much easier to understand than computer code [...] This is especially true if you have junior-level or intermediate-level people on your team.
This is why I'm a big fan of collective code ownership, pair programming, and frequent pair rotation. That has a variety of benefits. It also has substantial advantages over documentation. A big piece of which is that the need for documentation is always speculative, whereas answering a question always works from a confirmed need.
> It is also true if you ever end up coming back to some piece of code you yourself wrote a year ago.
This is what I use tests and journals for. Well-written tests are essentially machine-verifiable documentation. They tell me what the intent of the system is. If I want to know the history of the intent, then I turn to my journals.
> But look at it this way: code is for computers. Documentation is for humans.
I couldn't disagree more. As Martin Fowler says: “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
Code and tests are primarily means of communication between developers. They have the constraint that they should result in a running system. But we stuff most of the work of that into compilers, optimizers, and run times. Our tools are -- and should be -- optimized for human productivity. And since programming is mostly a team sport, the biggest value of our tools is in how they enable that teamwork.
- ethbro 10y agoThe biggest value in documentation to me has always been efficiency in understanding: that usually means documenting at the architecture / "components as black boxes" level. I could trace through to see how someone glued something together without having a hint what I'm looking for, or I could get the architecture gist and then generally know where the thing I should be looking at is. To me, this delivers two benefits. (1) Reduced redundancy / potential for divergence (as you mentioned above), as you're not re-documenting code but rather documenting at a higher level. (2) Reduced churn, as architecture changes more slowly than code, and generally an arch change will have some organizational process before being made (where docs can be updated). Disclaimer: This is coming from a place of diving into a lot of client systems with really poor or utterly lacking documentation.
- wpietri 10y agoSure, but no documentation here will be as efficient as an expert having a conversation with you and answering your questions. I'd much rather have a few whiteboard conversations and maybe some pair programming time, and that is cheaper and easier for everybody then speculative production of documentation. If the choices are only "shitty code with no docs" and "shitty code with good docs", I'll definitely take the latter. And if I'm rolling a team off a project, I'm happy to take some time to write some high-level docs for the people who will next pick it up. That's a one-time expense with documentation written for a defined audience. But when I'm picking up a system and the original team is gone, I'd much rather have good code and good tests over good docs. And honestly, I'm not sure I've even inherited a system with good docs. I have seen things that managers probably thought were good docs. And I've seen things that the developers intended to be good docs, and might have even been good once upon a time. But by the time I get to them, it's either the "we were told to write docs" garbage that is useless, or stuff that's so far out of date that it's just as often misleading as helpful.