Re:How I, a beginner developer, read the tutorial you, a dev...
by mlyle on Monday September 22, 2025 @02:06AM
(#45329605)
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.
Re:How I, a beginner developer, read the tutorial you, a dev...
by BrouteMinou on Monday September 22, 2025 @02:41AM
(#45329837)
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"...
Re:How I, a beginner developer, read the tutorial you, a dev...
by Nab443 on Monday September 22, 2025 @11:15AM
(#45334616)
When I type F5, my terminal writes "~" but nothing happens, what did I miss?
Re:How I, a beginner developer, read the tutorial you, a dev...
by zahlman on Monday September 22, 2025 @02:17PM
(#45337369)
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.
Re:How I, a beginner developer, read the tutorial you, a dev...
by mixmastamyk on Monday September 22, 2025 @01:53AM
(#45329529)
Indeed, snapshots are an amazing friend for this.
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.