[kostarelo]

It seems to me that all you want is to document a manual process. Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base .e.g in Confluence or as product requirements.

I can see the usage in an isolated team of a few people that will write these scripts for their own benefit.

I am opposed in general with having scarce information around. Better have everything a single place, whether that's a guide on how to provision a user or is how to add a new endpoint to your API or write a new end to end test.

[iainmerrick]

Having them documented in dump scripts is no different than having them documented as a guide in your knowledge base

It’s very different, in at least two ways:

- If your checklist is on a wiki, people may stop referring to the checklist once they’re familiar with the process. That’s bad if there are important changes. But if the process is “run this script and do what it says”, I think people are much more likely to keep doing that.

- When you start automating steps, people using the checklist pick up that automation for free. With a checklist on a wiki, any new automation means the user has to do something differently (eg maybe step 10 is “run this script” instead of “log on to the dev console and disable write access”)

[TuringTest]

There is one advantage of this script over an equivalent document: it provides the instructions in the same context that it's being used (the command shell).

Unless we have script shells that can universally launch a web document side-by-side from the shell prompt where it needs to be used, having it being displayed from the shell itself step by step will reduce the mental load required to follow the instructions. Also, the benefit of having an already semi-automated process in order to build a script in the future is not negligible.

[pojzon]

I think dual screen solution provides exactly that. Working only on a corporate laptop is very inefficient in this regard.

[lucideer]

In addition to the sibling commenters point about providing instructions in context, this approach has another much bigger advantage (mentioned in the article): it informs you of where you are in the process so you don't miss steps.

Keeping track of which step you are on while following a long doc is no easy task when some steps needs to be left unattended (and produce scrolling terminal output making viewing the last-run command harder).

[some_furry]

Furthermore, some tasks are nonlinear in complexity. Documenting those properly would quickly lead to a "choose your own adventure" type scenario.

Most documentation software (i.e. Wikis) do a poor job of encapsulating this. The "do-nothing" scripts might be easier to maintain, but it forces you to use plaintext.

I recently started an open source project that might be more helpful for teams (if for no other reason than it uses Markdown): https://faq.dhol.es/@Soatok/public-beta/what-is-faq-off

[imhoguy]

I find structure-free knowledge bases like Confluence becoming outdated quickly, lacking forking/merging (other customer has sligtly modified process), lacking enforced peer review (pull requests) or prone to company structural changes (NIH, "let's create new page in our space").

You can keep these scripts versioned in a repository next to the actual product code, with all benefits like forking, merging and pull-request reviews.