Technical writer discovers the joys of virtual machines

This week I started playing around with a virtual machine. Up to now, when I heard people talking about VMs, I thought “Oooer, no need for a tech writer to go there.” Now I’m there and it’s cool. It’s more than cool, it’s incredibly useful.

Imagine this: You need your own private configuration of a couple of servers running on a specific operating system, so that you can document the awesome ways that the servers and apps talk to each other. Setting them up is a pain and takes a lot of time. Besides which, there’s the minor problem that your own computer runs a different operating system. What if someone could simply copy a folder from their machine to yours, and you could click a couple of buttons to say:

Take that setup, make it mine and let me run it from here on in.

That’s what a VM (virtual machine) does for you.

What am I using a VM for?

I’m writing the documentation for the Confluence SharePoint Connector. The connector consists of a couple of plugins for Confluence wiki and a couple of SharePoint features. To run the connector, surprise surprise, you need both Confluence and SharePoint up and running, along with the bits and bobs that each demands.

As a technical writer, it’s really useful for me to have a “tame” version of the application I’m documenting, or at least a private area where I can create my own test data, test out the various “how to” scenarios I’m planning to write up, and create my use cases for screenshots. It’s positively blissful to know that they’ll all be there, unchanged, next time I go looking for them!

How did I get hold of a VM?

It just so happens that, in the course of testing the SharePoint Connector,  one of our awesome QA team members set up a VM that runs Windows Server 2003 with SharePoint MOSS 2007 and Confluence 3.1.

My own computer is running on Windows 7. Mark, the QA guy, simply copied a folder from his computer to mine. I downloaded and installed VMware Player on my machine. It’s free, easy to install and easy to use. I started it like any Windows application, and told it to open the “.vmx” file in the VM folder that Mark had given me.

Voila, a walking talking Windows Server 2003 desktop popped up in a window on my own Windows 7 machine, complete with the two browser windows and command window that Mark had left running last time he used the VM.

What does a VM look like?

Here’s the VMware Player window, showing the Windows 2003 desktop and the open applications in the Windows task bar at the bottom:

Technical writer discovers the joys of virtual machines

Technical writer discovers the joys of virtual machines

Here’s the VMware Player with SharePoint open in an IE window:

VMware Player with an IE window open:

VMware Player with an IE window open:

Here’s my entire desktop, showing Windows 7 on my own machine and the VMware Player running the Windows 2003 VM too. The VM looks just like another window. Click the image to see an expanded version:

Technical writer discovers the joys of virtual machines

Technical writer discovers the joys of virtual machines

In the above screenshot, the yellow square with 3 arrows, second from the right in the Windows task bar at the bottom, is the task bar button for the VMware Player. Just click it as you would any of the other apps.

You can of course expand the VM window so that it takes up your whole screen. Then it’s just as if you’re working on another machine entirely.

What happens when I shut my machine down?

That was a burning question in my own mind. I used VMware Player to “play” the VM. Then I started changing the VM. I added my own pages to Confluence. I added lists and sites to SharePoint. I installed Firefox. Will they all be there if I shut down the machine and start it up again, I wondered?

Being of an unduly cautious and untrusting nature, I decided not to risk it until I’d done most of what I needed to do. So I left my machine up and running overnight. But the goblins and gremlins came to visit, and somehow or other my machine rebooted itself anyway.

And yes, all my updates were still there when I opened the virtual machine again. Phew!

What you’re supposed to do before shutting down the host machine is to suspend the VM. If you take a look at the screenshots, you’ll see that the VMware Player window has a menu at the top. To suspend the VM, click “VM”, “Power”, “Suspend” in the VMware Player top menu. It says that this will preserve the VM for me. I’m not quite sure yet what the difference is between suspending and just shutting down willy nilly. I’m sure I’ll find out some time!

Anyway, I did it properly when shutting down for the Easter weekend, and suspended my VM. Here’s the VMware Player with the VM in suspended state:

Technical writer discovers the joys of virtual machines

Technical writer discovers the joys of virtual machines

Can I create my own VMs?

I can’t create my own virtual machines at the moment, because I’m only running VMware Player. The person who creates the VM needs more than just the player. I suspect that I’ll want to start creating my own VMs soon, though, just to see what it’s like. It will be very useful, for example, to have a VM with some flavour of UNIX running on my own box so that I can document the UNIX installation procedures.

Do you use VMs?

Where VMs really shine is if you need to run your software in different configurations, and even to store each configuration at specific points and be able to start it up again at each point later. I’d love to hear any stories or tips from people who’ve been using VMs longer than I have. If you haven’t tried them yet, it may be worth finding out if your QA or development teams regularly build VMs and if there are any that you may find useful.

A note about licences: Check your licence agreements for each piece of software running in the VM. You may need to get additional commercial or development licences. We have an MSDN subscription that takes care of many of the Microsoft licences.

As you can tell from the somewhat hazy wording of this post, I’m just starting to learn the joys of VMs. I hope you found it interesting. I’ll let you know if I do venture into building my own!

A virtual painting

I went for a walk in the Ozzie bush this morning. I rather like the shadows of the leaves on this tree trunk. It reminded me of a Japanese painting. Or something.

Technical writer discovers the joys of virtual machines

Technical writer discovers the joys of virtual machines


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 April 2010, in technical writing and tagged , , , , , , . Bookmark the permalink. 6 Comments.

  1. Great that you’ve discovered VMs – they really open up a whole new world of possibilities for tech writers. Since my primary platform is Mac OS X, I use a virtual machine to run Windows on my desktop to run the Windows-only apps I use – MadCap Flare, for example.

    • Hallo Ted, That’s a very interesting way to use a VM. I dropped in on your blog and saw that you’ve written a post about using MadCap Flare on a Mac (virtually). Thanks for letting me know about it!
      Cheers, Sarah

  2. Thanks for posting this! I’m a big fan of using VMs to help with Technical Writing and hope that part of the legacy I left my old colleagues with before coming to Australia was encouraging the team to embrace VM usage as I did. In a software company, it’s likely that the testers already use VMs and with VMWare Player and Microsoft VirtualPC (amongst others) being free downloads much like Adobe Reader, there’s no cost issue to stop us trying it out 🙂

  3. You may want to check out the virtual appliances available at as well. These are free virtual machines that you can download and try out open source platforms right out of the box.

    For instance, you may want to try out Apache and MySQL. There is a complete LAMP virtual appliance. There’s no configuration or anything. You just start up the VM and have a working LAMP server. As another example, say you wanted to try out the Magento e-commerce system. You would just download the virtual appliance and import it into your virtual machine software. I usually use VirtualBox. You fire up the VM and you have a fully installed and working Magento installation.

  1. Pingback: Technical writer discovers the joys of virtual machines | Technical Communication Center

  2. Pingback:   Weekly links roundup by Communications from DMN

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: