3 ms·

The biggest value in documentation to me has always been efficiency in understanding: that usually means documenting at the architecture / "components as black

by ethbro 9y ago

The 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 9y ago
Sure, 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.

by ethbro 9y ago

wpietri 9y ago

Sure, 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.