3 ms·
The author makes a cogent argument but I can't help thinking they've fallen into a 'perfect is the enemy of good' trap. Sure, 4doc doesn't perfectly describe ex
by onion2k 3y ago
The author makes a cogent argument but I can't help thinking they've fallen into a 'perfect is the enemy of good' trap. Sure, 4doc doesn't perfectly describe exactly how you should document everything, but it's better than every other approach I've encountered and that gives it a lot of value to me. It's likely that there isn't a documentation system that works perfectly for everything, especially if you accept an argument of 'this documentation system is a bit too verbose' which would stop you just enumerating everything imaginable.
You have to be pragmatic. If your docs could be improved by adopting a 4doc approach then you should, because they'll be better docs for it, even if the system is technically flawed. Similarly, if you have a doc that doesn't fit anywhere in the 4doc system but it's a useful doc, then it's still worth adding. 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. That's fine.
- brianpan 3y agoThe last section is titled "Good is the enemy of better".
- sundarurfriend 3y agoI don't think you and the author disagree at all. They say > I’m glad that people use it. I’m also a little frustrated that people use it even when its inappropriate. > I’ve read plenty of good 4doc pages. Even so, it still leads to the same kind of “this is the only way” thinking. People use the model even when it’s not the right choice and they don’t vary up the format even when they should. and you say > 4doc is a process. It is not perfect, but it's still useful, and you might need to step outside of it occasionally. --- The specific issue here is that it seems like the author has come across many people who use the 4doc model dogmatically. The article is geared specifically towards them, and is not an attempt to tear down the 4doc model as a whole.