3 ms·

Docs should start out as a rough scaffolding that is easy to change, then filled in as the product anneals. The reason is that systems evolve as you build them,

by daenz 4y ago

Docs should start out as a rough scaffolding that is easy to change, then filled in as the product anneals. The reason is that systems evolve as you build them, and constantly updating the docs to be consistent as the evolution occurs is an error prone chore that not everyone has the patience or diligence for. Assuming that your systems evolve as you create them, if you "complete" your docs too soon, you end up with less accurate docs than if you complete them later. Out of date docs are often harmful and demoralizing because they break trust.

maguay 4y ago
Author here, great point. Tony Fadell mentioned something similar in his Build book, about writing a press release before building your product. He mentions to pull the press release back out a few months into the project, and use the press release as a way to see what needs cut or what is critical to add. Or, if everything's changed too much, rewrite the press release. Scaffolding's a great example; it needs to morph as the project scope changes, but can also help set the scope (or at least direct it) at the start. At the very least, it gives you something to say ok, we're good to stop here, everything else can wait for v2.
alex_suzuki 4y ago
100% this. Outdated documentation is worse than no documentation. „Tell me you don’t care about your product without telling me you don’t care about it“. What I like to do is write a rough, high-level description of some core concepts that I don’t expect to change (they do, eventually). Just to get the ball rolling, and as a form of validation - if you can’t explain how something works, you either don’t understand it well enough or it‘s to complicated/convoluted.
dmitriid 4y ago
I've found out that "prototype fast, then document extensively as you re-write" a great approach. Because you've fleshed out the ideas, found out what works and what doesn't, and now you can capture all that in docs. However, as always YMMV and you might not get the luxury of re-writing :)
b3morales 4y ago
> Out of date docs are often harmful and demoralizing because they break trust. I agree, however the flipside failure mode is the initial rough design checks the "design doc" box and is never updated, so it remains vague and/or inaccurate. Any process ultimately is only as strong as the people following it.

by daenz 4y ago

maguay 4y ago

Author here, great point. Tony Fadell mentioned something similar in his Build book, about writing a press release before building your product. He mentions to pull the press release back out a few months into the project, and use the press release as a way to see what needs cut or what is critical to add. Or, if everything's changed too much, rewrite the press release. Scaffolding's a great example; it needs to morph as the project scope changes, but can also help set the scope (or at least direct it) at the start. At the very least, it gives you something to say ok, we're good to stop here, everything else can wait for v2.

alex_suzuki 4y ago

100% this. Outdated documentation is worse than no documentation. „Tell me you don’t care about your product without telling me you don’t care about it“. What I like to do is write a rough, high-level description of some core concepts that I don’t expect to change (they do, eventually). Just to get the ball rolling, and as a form of validation - if you can’t explain how something works, you either don’t understand it well enough or it‘s to complicated/convoluted.

dmitriid 4y ago

I've found out that "prototype fast, then document extensively as you re-write" a great approach. Because you've fleshed out the ideas, found out what works and what doesn't, and now you can capture all that in docs. However, as always YMMV and you might not get the luxury of re-writing :)

b3morales 4y ago

> Out of date docs are often harmful and demoralizing because they break trust. I agree, however the flipside failure mode is the initial rough design checks the "design doc" box and is never updated, so it remains vague and/or inaccurate. Any process ultimately is only as strong as the people following it.