Archive for October, 2009

Magic waterfalls

October 20, 2009

I was invited to speak as a guest lecturer at the Australian National University last week. The audience was a class of third and fourth year computer science students, and the topic was technical writing. After speaking for somewhere pretty close to an hour, and successfully getting a few laughs in that time, I answered a clutch of questions, and was then drawn into a discussion about engineering methods. The course convener had pointed out that the five-phase model (that I discussed at least briefly in this blog post) that I use is, in itself, a fairly typical engineering process. And of course he’s absolutely correct. It’s a perfectly ordinary process, based on the waterfall model.

It’s called a waterfall model because if you start at the top, the results of the first step are used to move into the second step, just like water flowing down a series of steps into a pool.

The students I was speaking to are at a point in their projects where they need to be producing some documentation. For a bunch of budding engineers this process can be a little daunting, and the question came up about the best way to tackle it. The answer is fairly simple – start the top of the waterfall, and let the current take you. By answering a few questions in the information plan, you can start creating a content specification. Using the chapter headings and source information you developed in the content spec, you can write the document.  Once it’s written, you can publish it, once it’s published you can review it, and then you’re ready to start again at the top with the next project.

Technical writing is less of a creative process, and more of a scientific process than just about any other kind of writing (with the possible exclusion of some kinds of academic writing).  The creativity only becomes important when you try and turn it from something dry and boring, to something magical.

Anyone with a scientific or engineering mind can create technical documentation, they might not enjoy it, but they are more than capable of creating it. It takes an artist to make it something wonderful, to turn it into something that people actually want to read, and to make it shine. It’s the difference between ‘magic’ and ‘more magic’.

Cross-posted to On Writing, Tech, and Other Loquacities


Haiku: A Journey

October 16, 2009

Warning: following these instructions will not result in the successful installation of Haiku onto an iMac G3.

It’s my first morning as a technical writer, and I’m presented with a challenge: install Haiku on a Mac. And not just any Mac. An iMac G3: Bondi Blue; at least ten years old; and well past anything resembling its prime.

Anybody need a good working definition of ‘character building exercise’?

For those, like myself, who know little or nothing about Haiku (the operating system, not the poetic form), it is an open source operating system. Currently in active development, Haiku is designed to be compatible with BeOS.

To make things a little easier, I was given a CD with the Haiku bootloader on it and a link to instructions for installing Haiku using such a CD. Unfortunately, the iMac couldn’t read the CD. Instead it needed to download the file from another computer running a TFTP server. So I unplugged my laptop from the network and got to work.

Skimming through the Red Hat Enterprise Linux 5 Installation Guide, it became clear: to set up a TFTP server, my laptop had to be the DHCP server for a new network. I followed the reference to the Red Hat Enterprise Linux 5 Deployment Guide and delved into the section on setting up a DHCP server.

One problem arose: the Deployment Guide has no installation step in its procedure for setting up a DHCP server. Configuration is covered, but it assumes the DHCP server package is already installed, which was not the case on my laptop. So I filed a bug report and began the hunt. After a number of frustrating dead ends, I resorted to Yum Extender (yumex), and found it by trawling through every package which mentioned DHCP in the package name or description.

The needed package was dhcp, by the way: sudo yum install dhcp and I was back on track.

Now that I had a DHCP server installed, I was ready to install the TFTP server. Or was I? According to Chapter 21.2, Configuring a DHCP server, I had to create a new file — /etc/dhcpd.conf — for it to all work. So I did. And it didn’t work. So I copied the sample file mentioned in Chapter 21.2 straight into the /etc/ directory. That didn’t work either. I tried multiple changes, including rewriting dhcpd.conf myself.

In the end, the solution was fairly simple. Between Red Hat Enterprise Linux 5 and Red Hat Enterprise Linux 6 alpha, the directory had moved. What had been /etc/dhcpd.conf was now /etc/dhcp/dhcpd.conf. So, with the new directory sorted out, the DHCP server was online. Success, yes? No.

After editing dhcpd.conf according to the instructions in Chapter 21.2.1, I checked to see if the TFTP packages were installed on my laptop. They weren’t. So I loaded yumex once again and searched for the packages required for the TFTP server. I installed those, and then used the chkconfig command to see if the TFTP server was configured to start automatically. It wasn’t. I entered the commands as per the Installation Guide, Chapter 34.4.1 to bring it online, and checked again. Everything was now up and running.

Next step was the bootloader file, which I copied to /var/lib/tftpboot/ on my TFTP server. Then I put the CD back into the iMac; checked the network cables; and tested to see if the iMac (which was at this point booting into Linux) had received an IP address from my laptop. It had, so I started to tick off the list. Step one; check. Step two; check. Step three; check. Step four; check.

Step five? It failed. So, I booted the iMac and gave the four-fingered salute, Command-Option-O-F. Rather than finding myself at an Open Firmware prompt, as expected, I watched the machine boot into Linux again. Incongrously enough, Open Firmware would not open. After numerous attempts, we detached the ancient keyboard and attached a brand-new one. It worked perfectly.

Step five? Check.

Two steps from success.

After booting to the Open Firmware prompt I typed in the boot command specified in the procedure and waited. And waited. And all I got back was load-size=0. Load-size too small? Too large I could have understood, though the openfirmware_boot_loader file is only 231 kB. This was, perhaps, the most perplexing hurdle. But it was overcome, like all the others, with a touch of simplicity. The firewall for the laptop was turned off, and after a moment’s hesitation, the iMac transferred the file across.

There it was. Ready to install. Except it still didn’t work.

Those of you who took a moment to read the step-by-step guide may have noticed the paragraph at the bottom of the page which notes the kernel for loading Haiku via a TFTP server is currently broken.

At the bottom of the page. After the installation instructions.

Hence the warning at the top of this page. It seemed the polite thing to do.

Educating Developers about XML Content Authoring – The MCDUG.

October 1, 2009

In my gig as a Technical Writer for Red Hat Brisbane, I have the opportunity to work with incredibly skilled Open Source developers, and write about cutting edge technology in the Open Source software arena.

Sometimes, it is necessary to step away from documenting the technology aspects of an Open Source project, and focus on writing content that will help a team work together more effectively. I’m talking about writing documentation that supports aspects of an open source project, not what the open source project is working on. Yes, I’m talking about a procedures guide.

The Mobicents team expressed interest in taking back ownership of the community XML documentation being maintained by Red Hat. The decision had a number of positive effects:

  • Developers could contribute directly to the user documentation.
  • The open source community had access to the community content source.
  • The Red Hat Content Author (me) could focus on developing the Red Hat product documentation for the project.

Because the team was going to be writing the initial content themselves, I realised that the Self Managed Community Documentation (SMCD) project would fail quickly if the development team did not have clearly defined processes, clear grammar guidelines and support with XML authoring.

I decided to take a step back from writing content for the software, and invested time in creating the Mobicents Community Documentation User Guide (MCDUG). I had to juggle urgent documentation tasks with my MCDUG writing, but the juggling act was worth it.

I have completed the first full release of the MCDUG. The guide is hosted on the Hudson build server, and is freely available to anyone who wishes to read it. Much of the guide contains information that will only be relevant to Mobicents Developers, however there is some useful information about DocBook XML structure that may be useful to those new to XML Authoring.

I’ve been referring new Red Hat Content Authors to the structure tips contained in the MCDUG, and the information seems to be helping them get accustomed to working with XML faster. My ultimate hope is the MCDUG will be used regularly by the Mobicents developers, and will continue to evolve with the SMCD project. After all, a procedures guide is only relevant if the procedures are relevant.