You can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there.

My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play".

That's not always possible, so then the exercise becomes to simply document each step, ideally with both English words and a CLI snippet.

▲

mlyle 5 days ago | parent | next [-]

I agree that testing from a vanilla machine is important.

But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can.

And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.

▲

BrouteMinou 5 days ago | parent | prev | next [-]

Yes, more of this!

I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md.

If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...

▲

Nab443 4 days ago | parent [-]

When I type F5, my terminal writes "~" but nothing happens, what did I miss?

	▲	zahlman 4 days ago \| parent [-]
		In case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.

▲

mixmastamyk 5 days ago | parent | prev [-]

Indeed, snapshots are an amazing friend for this.