3 ms·

Documentation is great and all, but no one ever talks about when theres too much. Maybe because it's rare? At big companies I've seen "architects" churn out pag

by pram 5y ago

Documentation is great and all, but no one ever talks about when theres too much. Maybe because it's rare? At big companies I've seen "architects" churn out page after page of diagrams, design docs, runbooks, checklists, descriptions, etc. There is so much information that it becomes practically useless in aggregate, because no one is reasonably going to read it all. I'm not going to pretend that I have the patience or the attention span to have the gnostic mysteries of our Kubernetes infrastructure revealed to me.

zelphirkalt 5y ago
In such cases I wish for a "cookbook" style of additional documentation, that I can search, to find examples for doing, what I want to do.
qayxc 5y ago
Nothing a good search engine and proper requirements can fix. In theory it should work like this: I) "User should be able to do X" <- requirement II) "X can be achieved by performing steps A, B, and C" <- description of the implementation (high-level, user-perspective) III) "A works by using components 1 and 2" <- technical documentation (design-level, architecture perspective) etc. I) generates your index (what can I even do with the software) II) generates the documentation (how can I do it) III) and below is for technical use only (extending, modifying, porting) Stuff like rationales for design decisions can be structured in the same layered way. I don't know how something like this can be extracted after the fact, but no matter the development model (waterfall/agile), a structure like this should arise naturally anyway and the absolute amount of documentation isn't a problem. Lack of proper structure, however, is.
0xbadcafebee 5y ago
There is no such thing as too much documentation. There is out of date documentation, inaccessible documentation, unindexed documentation, poor documentation, redundant documentation, etc... But what you described is amazingly valuable. Just because it's not valuable to you, right now, doesn't mean there's too much of it.

by pram 5y ago

zelphirkalt 5y ago

In such cases I wish for a "cookbook" style of additional documentation, that I can search, to find examples for doing, what I want to do.

qayxc 5y ago

Nothing a good search engine and proper requirements can fix. In theory it should work like this: I) "User should be able to do X" <- requirement II) "X can be achieved by performing steps A, B, and C" <- description of the implementation (high-level, user-perspective) III) "A works by using components 1 and 2" <- technical documentation (design-level, architecture perspective) etc. I) generates your index (what can I even do with the software) II) generates the documentation (how can I do it) III) and below is for technical use only (extending, modifying, porting) Stuff like rationales for design decisions can be structured in the same layered way. I don't know how something like this can be extracted after the fact, but no matter the development model (waterfall/agile), a structure like this should arise naturally anyway and the absolute amount of documentation isn't a problem. Lack of proper structure, however, is.

0xbadcafebee 5y ago

There is no such thing as too much documentation. There is out of date documentation, inaccessible documentation, unindexed documentation, poor documentation, redundant documentation, etc... But what you described is amazingly valuable. Just because it's not valuable to you, right now, doesn't mean there's too much of it.