4 ms·
Imagine that a guy who automated a certain part of the process just left, and you need to make some changes. Who's holding the knowledge about how X is automate
by orbital-decay 7y ago
Imagine that a guy who automated a certain part of the process just left, and you need to make some changes. Who's holding the knowledge about how X is automated and the thought process behind it?
- onei 7y agoIdeally, the automation is available and can be read through to divine the steps it is taking to perform the task. As for the thought process, pray that the author left behind hints whether that be in the form of comments in code, descriptive commit messages, etc. Otherwise it gets a bit more tricky.
- onion2k 7y agoComments and commit messages are documentation and knowledge capture, but done in a way that's really hard to read through and requires technical knowledge and repo permissions to even access. If your team includes people who aren't developers and you need to review a process it's very useful to have that knowledge in a more readable format.
- onei 7y agoI don't disagree with the overall point, but I'm not sure a non-developer would have a need to understand the specifics of how a task is automated. In theory, the automation is built off a defined process already which should be readily available to non-developers already. In practice... Well, the initial question was about good practices so perhaps we shouldn't lift the lid on bitter experience.
- prepend 7y agoI don’t like having extra steps to convert things to more readable formats because it’s expensive and boring and tends to get out of sync very quickly. If non-tech people on a team need to understand, in detail, a technical process, I think it’s easier to teach them to read through a script than to pay a tech writer to document the script, all the time. I’ve run into this problem with non-technical project managers who want to understand in detail. If this level of understanding is necessary then it’s possible to scan a source file to read comments. Or generate documentation from source and dump it on a web server somewhere. Although lately even non-technical people are able to read and edit markdown files on GitHub.
- maxerickson 7y agoYeah, I think if you are looking at commit messages to understand a process, you have to take a look at if/where things went wrong.
- matwood 7y agoAt worst, the code is there. This is much better than a person leaving who did some stuff manually. Obviously additional documentation would be great, but code itself is a minimal type of documentation.
- orbital-decay 7y agoYes, but the lack of reasoning behind the implementation means that the new person has to reverse engineer it (practically speaking). This isn't always bad, but in most cases it is. My point was that by simply automating the process you don't institutionalize the knowledge as much as you move at least part of the problem somewhere else. It heavily depends on the application, though. In my domain the implementation is rarely self-documenting, and most of the system's complexity is usually baked into the spec or the human part of the process. In some other domains the proportion is completely different.