: If your audience is modifying code whatsoever, they should be using version control. Either you assume they already know how, or you first walk them through the basics before getting into tasks

@Shanna875

Vote Up Vote Down

If your audience is modifying code whatsoever, they should be using version control. Either you assume they already know how, or you first walk them through the basics before getting into tasks that require modifying code. Then, when it comes time for them to make N steps of modifications without being able to test, you can show them the expected output of git diff or git status or similar, and that's what they use to verify that they followed each step correctly and that the working tree is in the state you expect them to have it in.

While I came up with and wrote this with OP's specific task in mind, I think the same principle applies with a lot more generality. If you can't give the reader steps where the [technical thing] being modified works in a testable way after each step, you instead should give them ways to observe/measure the results of their actions at each step. This may take the form of descriptions of how a physical object should look from different perspectives, points of measurement to check for consistency, etc. A particular example of technical writing I'm familiar with that does not follow this practice well is the Haynes manuals for automotive repair, and it's often really frustrating not being given any information to tell if you've found/removed the appropriate part.

(0)

Login to post a comment!