4 ms·

Ideally, 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 aut

by onei 7y ago

Ideally, 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 ago
Comments 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 ago
  I 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 ago
  I 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 ago
  Yeah, 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.

by onei 7y ago

onion2k 7y ago

Comments 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 ago
I 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 ago
I 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 ago
Yeah, 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.