dennisgorelik: (Default)
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:
Read more... )
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.
dennisgorelik: (Default)
I asked a developer on my team to commit code frequently: at least once per day or more.
Even if feature is not ready - commit parts of this feature, prototypes, or even mixture of draft code and draft notes.

The developer objected that:
1) Not every feature fits into one day of development. (I agree with that).
2) Commiting raw code, and especially committing raw notes - effectively publishes them.
And publishing raw ideas - makes them to prematurely solidify, which, in turn, negatively affects future research, because there is a bias toward solid ideas, while alternative solutions are more likely to lose even if they are good.
(I kind of agree with that effect, but only partially. Publishing ideas solidify them a little, but that effect is more positive than negative).
3) Commiting/publishing raw notes violates developer's privacy, because raw notes represent unfiltered train of thoughts.
(My thinking is that since these notes were created as an attempt to find a solution to a work problem - there raw notes are very unlikely to contain any personal secrets. Raw notes can still contain weird thoughts or even silly mistakes, but that is OK - there is no need to be ashamed of mistakes in early research thoughts).

My main reasons to have code committed frequently is:
1) Check that work goes in the general direction that is likely to satisfy business goals.
2) Review new research and code in reasonably small chunks, so that code reviewer is able to understand them.
3) See not only final polished solution, but also mistakes and research dead ends along the way. That helps learning more.

What do you think: is trying to commit code at least once per day - too frequent or a good goal?
dennisgorelik: (2009)
Google Maps API team just sent me couple of emails.
The gist of the changes is that:
1) Going forward Google Maps API strongly encourages using API key, even from JavaScript version that runs from users' browsers.
2) "Google Maps JavaScript API" and "Google Maps Geocoding API" are going to use free quota associated with that API key.
That means Google is likely to start charging for these requests much sooner.

The prices are not high: $0.50 per 1000 requests.
That means for 1 cent we can make 20 requests.

It is a good deal for Geocoding API that we really need.
It is not such a good deal for rendering Google Maps snippets on our web site, because we do not really need them that much.

So far I plan to ignore their advise "to begin using a key for all requests immediately.", and rely on their claim that "For the time being your domain has been whitelisted for keyless usage."
I guess using keyless requests from browser should be ok. (PostJobFree already uses API key for server-side requests to Google Maps Geocoding API).

I am also tempted to remove Google Maps from jobs and resume pages on postjobfree.com
It is not obvious if having these Google Maps snippet our PostJobFree pages adds value to our users.

What do you think I should do?
From: Google Maps APIs 
To: catchall@r.postjobfree.com
Date: Wednesday, June 22, 2016, 8:43:08 PM
Subject: [Action required] Google Maps API requests are missing a project key

===8<==============Original message text===============
This email is intended for the administrator of postjobfree.com. If you are not affiliated with postjobfree.com, please disregard.

Hello developer,

Today we announced updates for the Google Maps API Standard Plan, including marking keyless usage of any of the Google Maps APIs as unsupported. As part of these changes, we are attempting to contact developers making requests without a key to advise them of possible impacts to their implementation.

We notice that postjobfree.com is accessing Google Maps APIs without a key and believe you may administer that domain. For the time being your domain has been whitelisted for keyless usage. However, API keys allow Google to protect an application's uptime and contact developers with mandatory service announcements, therefore we advise you to begin using a key for all requests immediately. 

To register a free API key for your application:
Visit the Google API Manager Console.
Create or select a project and click "Continue" to enable APIs and related services.
On the Credentials page, get a Browser Key (and set the API credentials).
Add your API key to all application requests.
To prevent quota theft, secure your API key following these best practices.
(Optional) Enable billing. See Usage Limits for more information.
Note if you have an existing Browser key, you may use that key.
For more information on these changes, please refer to the Standard Plan updates summary.

Thanks for using our APIs, 
The Google Maps API team 
© 2016 Google Inc., 1600 Amphitheatre Parkway, Mountain View, CA 94043 
You've received this mandatory email service announcement about important changes to your Google Maps for Work product or account. 
===8<===========End of original message text===========


Update: Decline of Google Maps team

Profile

dennisgorelik: (Default)
Dennis Gorelik

July 2017

S M T W T F S
      1
2345678
9 101112 131415
161718192021 22
23242526272829
3031     

Syndicate

RSS Atom

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Jul. 24th, 2017 02:28 am
Powered by Dreamwidth Studios