4 ms·

> Or rather, how does one avoid getting into this situation. Documentation?

by ISL 6y ago

rantwasp 6y ago
nah. documentation only goes so far. you handle this by having and exercising a disaster recovery plan and having (and listening to) competent people that would spot this issue in a jiffy.
- foobiekr 6y ago
  This. I actually think just documentation is, well not completely worthless but close to. Imagine telling someone they could learn to weld airframes by reading. Just no.
  - twobitshifter 6y ago
    For software, it’s the maintenance task that’s helped by documentation not building. They still need to know how to build but it’s a lot easier with documentation. I know that when we use software packages we all rely on the documentation to understand how to use it and code our desired behaviors. It’s obvious that our own code can benefit from documentation in the same way.
    - rantwasp 6y ago
      documentation is required but not sufficient. also, documentation is usually outdated really fast if the person maintaining the system leaves and/or does not care
giantrobot 6y ago
The issue with "documentation" is there are never enough resources devoted to it at most companies. When given a schedule it only covers the main project goal(s) and no time for documentation or refactoring or any quality of life improvements. Significant documentation is also not something easily written in slack time. With any non-trivial project good documentation is a full time effort. It also needs to be updated as the project evolves lest it become out of date and incongruous with the behavior of the system. There's dreams of in-line documentation but that's only going to cover individual methods and classes and not necessarily whole modules or major subsystems of a project. It's also not going to necessarily cover in-line documentation from other parts of a project in different languages e.g. comments in config files. There's lots of technical ways to help documentation but there's no replacement for documentation being a high level project goal with resources allotted to it.
- gregmac 6y ago
  Part of a way around this is broadening your definition of "documentation". For example, in code: good naming, simple structure, unit tests, and useful comments all can count. A set of easy-to-understand unit tests that cover real scenarios is much better than even the greatest documentation ever written. A fully scripted build and ideally also deployment (CI/CD pipeline) beats a checklist with tens of items that have to manually followed. An issue system with good descriptions of changes (including why and what), reproduction steps, expected outcomes, links to related issues, etc also can go a long way. All of this stuff has the side effect of making day-to-day work simpler, overall, while actually just being a part of that work.
  - giantrobot 6y ago
    > For example, in code: good naming, simple structure, unit tests, and useful comments all can count. A set of easy-to-understand unit tests that cover real scenarios is much better than even the greatest documentation ever written. 1. Naming things is hard. It's a bit of a joke but good descriptive yet usable naming is hard. It can get harder after refactoring or adding in features you didn't expect the last time you were in the module. 2. Project structures start out simple. Then you need to add some feature or fix some major issue with a due date of last week. As a project gets bigger the simple structure of yesterday might not serve the needs of today. Resources for refactoring are usually somewhere around the priority level of "Good Documentation". 3. Comments need maintenance like explicit documentation. Tight schedules lead to "# TODO add documentation here". Then you get the assholes that believe comments or in-line documentation is something you put in check in notes. 4. A "unit test" that covers a "real scenario" is not a damned unit test. It's an integration test (or however you label it) and it's not likely something your CI/CD system can run on the regular. If a real scenario is touching a production-load DB or something it's a big deal to run the test. Tests like that need resources to run and non-trivial resources to write. You're not just making sure a method returns a float or throws an error correctly. I'm not saying your suggestions are bad or shouldn't be used. The issue is management rarely sees any value with documentation, tests, or even code cleanliness. They're rarely incentivized to care about those things so they don't. They get their bonus on feature checkboxes or hitting a deadline. At the end of a project they'll schedule a "documentation" sprint or some dumbass thing that accomplished little useful output. It's worse when you've got a "move fast break things" chanting moron doing the scheduling.

> Or rather, how does one avoid getting into this situation. Documentation?

by ISL 6y ago

> Or rather, how does one avoid getting into this situation. Documentation?

nah. documentation only goes so far. you handle this by having and exercising a disaster recovery plan and having (and listening to) competent people that would spot this issue in a jiffy.

foobiekr 6y ago
This. I actually think just documentation is, well not completely worthless but close to. Imagine telling someone they could learn to weld airframes by reading. Just no.
- twobitshifter 6y ago
  For software, it’s the maintenance task that’s helped by documentation not building. They still need to know how to build but it’s a lot easier with documentation. I know that when we use software packages we all rely on the documentation to understand how to use it and code our desired behaviors. It’s obvious that our own code can benefit from documentation in the same way.
  - rantwasp 6y ago
    documentation is required but not sufficient. also, documentation is usually outdated really fast if the person maintaining the system leaves and/or does not care

giantrobot 6y ago

The issue with "documentation" is there are never enough resources devoted to it at most companies. When given a schedule it only covers the main project goal(s) and no time for documentation or refactoring or any quality of life improvements. Significant documentation is also not something easily written in slack time. With any non-trivial project good documentation is a full time effort. It also needs to be updated as the project evolves lest it become out of date and incongruous with the behavior of the system. There's dreams of in-line documentation but that's only going to cover individual methods and classes and not necessarily whole modules or major subsystems of a project. It's also not going to necessarily cover in-line documentation from other parts of a project in different languages e.g. comments in config files. There's lots of technical ways to help documentation but there's no replacement for documentation being a high level project goal with resources allotted to it.

gregmac 6y ago
Part of a way around this is broadening your definition of "documentation". For example, in code: good naming, simple structure, unit tests, and useful comments all can count. A set of easy-to-understand unit tests that cover real scenarios is much better than even the greatest documentation ever written. A fully scripted build and ideally also deployment (CI/CD pipeline) beats a checklist with tens of items that have to manually followed. An issue system with good descriptions of changes (including why and what), reproduction steps, expected outcomes, links to related issues, etc also can go a long way. All of this stuff has the side effect of making day-to-day work simpler, overall, while actually just being a part of that work.
- giantrobot 6y ago
  > For example, in code: good naming, simple structure, unit tests, and useful comments all can count. A set of easy-to-understand unit tests that cover real scenarios is much better than even the greatest documentation ever written. 1. Naming things is hard. It's a bit of a joke but good descriptive yet usable naming is hard. It can get harder after refactoring or adding in features you didn't expect the last time you were in the module. 2. Project structures start out simple. Then you need to add some feature or fix some major issue with a due date of last week. As a project gets bigger the simple structure of yesterday might not serve the needs of today. Resources for refactoring are usually somewhere around the priority level of "Good Documentation". 3. Comments need maintenance like explicit documentation. Tight schedules lead to "# TODO add documentation here". Then you get the assholes that believe comments or in-line documentation is something you put in check in notes. 4. A "unit test" that covers a "real scenario" is not a damned unit test. It's an integration test (or however you label it) and it's not likely something your CI/CD system can run on the regular. If a real scenario is touching a production-load DB or something it's a big deal to run the test. Tests like that need resources to run and non-trivial resources to write. You're not just making sure a method returns a float or throws an error correctly. I'm not saying your suggestions are bad or shouldn't be used. The issue is management rarely sees any value with documentation, tests, or even code cleanliness. They're rarely incentivized to care about those things so they don't. They get their bonus on feature checkboxes or hitting a deadline. At the end of a project they'll schedule a "documentation" sprint or some dumbass thing that accomplished little useful output. It's worse when you've got a "move fast break things" chanting moron doing the scheduling.