?

Log in

 
 
13 July 2017 @ 05:57 pm
How to write good instructions  
How-to create a VM on Hyper-V
Yesterday I learned how to setup a new virtual machine from scratch on Hyper-V.
Then I created an instruction for that:

-----
1) Install "Hyper-V" (if not installed yet)
https://superuser.com/questions/568425/hyper-v-virtualisation-disabled-in-firmware

2) Launch "Hyper-V Manager".

3) Create Virtual Network Switch (if not created yet)
- Right-click "RONAM" -> "Virtual Switch Manager".
- "New virtual network switch" -> "External" -> click [Create Virtual Switch].
- Make sure that "External network" is selected.
- Make sure that "Intel(R) Ethernet Connection (2) I219-LM" is selected.
- Click [Apply].
- "Pending changes may disrupt network connectivity" popup would show up. Click [Yes]. Wait for ~10 seconds.

4) Right-click "RONAM" and select "New" -> "Virtual Machine".

5) "Specify Name and Location"
Name: "BaseVM"
Location: "C:\VM"

6) "Specify Generation"
Select "Generation 2" radiobutton.

7) "Assign Memory"
Startup memory: 4096 MB 

8) "Configure Networking"
Connection: "VS2017Switch"

9) "Connect Virtual Hard Disk"
Select "Create a virtual hard disk" radiobutton.
Size: 80 GB.

10) "Installation Options" sub-tab
Select "Install An Operating System From A Boot CD/DVD-ROM".
Image file (.iso): "C:\install\en_windows_server_2016_x64_dvd_9718492.iso"

11) "Summary"
Click [Finish].

12) Right-click "BaseVM" -> "Start".
That would start Windows installation.
-----

Then I asked K. (a developer on my team) to test my instruction by creating a new VM from scratch and fix the instruction if needed.

The "fix"
K. successfully created new VM and "fixed" the instruction by adding small details to it. That effectively made that instruction about 25% longer:

=====
0) Create "C:\VM" folder (if not created yet)
1) Install "Hyper-V" (if not installed yet)
https://superuser.com/questions/568425/hyper-v-virtualisation-disabled-in-firmware

2) Launch "Hyper-V Manager".

3) Create Virtual Network Switch (if not created yet)
- Right-click "RONAM" -> "Virtual Switch Manager".
- "New virtual network switch" -> "External" -> click [Create Virtual Switch].
- Make sure that "External network" is selected.
- Make sure that "Intel(R) Ethernet Connection (2) I219-LM" is selected.
- Click [Apply].
- "Pending changes may disrupt network connectivity" popup would show up. Click [Yes]. Wait for ~10 seconds.

4) Right-click "RONAM" and select "New" -> "Virtual Machine".

On "Before you begin" screen:
Click [Next]

5) On "Specify Name and Location" screen:
a) Name: BaseVM
b) Check "Store the virtual machine in a different location" checkbox.
c) Location: "C:\VM\"
Click [Next]

6) On "Specify Generation" screen:
Select "Generation 2" radiobutton.
Click [Next]

7) On "Assign Memory" screen:
Startup memory: 4096 MB 
Click [Next]

8) On "Configure Networking" screen:
Connection: "VS2017Switch"
Click [Next]

9) On "Connect Virtual Hard Disk" screen:
Select "Create a virtual hard disk" radiobutton.
Size: 80 GB.
Click [Next]

10) "Installation Options" screen:
Select "Install an operating system from a bootable image file".
Image file (.iso): "C:\install\en_windows_server_2016_x64_dvd_9718492.iso"
Click [Next]

11) On "Completing the New Virtual Machine Wizard" screen:
Click [Finish].

12) On "Virtual Machines":
Right-click "BaseVM" -> "Start".
That would start Windows installation.
=====
What went wrong
Formally, that "fixed" instruction is correct -- clicking "Next" button is one of the likely steps that person would take in order to go through new VM settings.
However including "Click [Next]" steps into the instruction makes instruction worse and not better, and here is why:
1) The longer the instruction - the harder it is to read, understand, and follow that instruction.
It is also harder to review and modify longer instructions.
2) The obvious steps in an instruction - distract the reader from the non-obvious steps, such as "what 'Generation' option to choose" and "how much RAM to allocate".
3) Any user who is going to create a new VM from scratch does not really need to get instruction on how to operate the wizard:


Understand your readers
Here is a rule that K. violated by "fixing" the instruction:
Do NOT include into instruction steps that are obvious for all likely readers of that instruction: if the reader is able to reliably figure out an omitted step in a few seconds - then this step does not belong to the instruction.
However if the step is obvious only for some readers and is not obvious for other readers - then such step should be included into the instruction (because it is much more time consuming to figure out non-obvious step than to skip obvious instruction steps).

Understand your goals
Another important consideration when writing instructions - is to clearly understand the purpose of the instruction. I knew why I needed that instruction:
1) To help developers on my team to quickly familiarize themselves with setting up Hyper-V VMs.
2) In the future - to remind me and other developers key steps we used in creating our VMs.
3) To have a source file that we can edit to reflect key choices in configuration of our VM.

K. did not have these goals in mind and, actually, thought that such "VM setup" instruction is useless, but puffed up the instruction anyway. According to his belief - all instructions must be written in such a way that even a dummy would be able to follow it. The mistake here is to assume that the dummy (who does not know how to navigate a wizard) would actually read our instruction.

Originally posted at: http://dennisgorelik.dreamwidth.org/136094.html
 
 
 
Yaturkenzhensirhiv - a handheld spyyatur on July 14th, 2017 03:16 am (UTC)
Well, all I can say is you are right. Every set of instructions should be design with a specific target audience in mind. If you expect your target audience to "Install Hyper-V" without any further clarification, then it is reasonable to assume they would know how to click "Next".
Dennis Gorelikdennisgorelik on July 14th, 2017 04:59 am (UTC)
I also pushed a little bit further and assumed that
Check "Store the virtual machine in a different location" checkbox.
should be omitted, because the reader would very quickly figure out that in order to enter "Location:" he has to click that checkbox.

Edited at 2017-07-14 05:00 am (UTC)
Clean and soberanspa on July 14th, 2017 04:34 am (UTC)
Prediction: then they would release another SP and Hyper-V admin app would look different and the setup scenario will change.
Dennis Gorelikdennisgorelik on July 14th, 2017 04:46 am (UTC)
If insignificant details are omitted from installation instruction, then most of wizard changes (from Windows service pack) would NOT affect that instruction.
And even if some changes would creep in - it would be easy to figure out how to deal with these changes and how to update slim installation instruction.