Turning a comma-separated list into an <itemizedlist>

February 13, 2010 by

Something I encounter occasionally is a comma-separated list of items in a paragraph that really should be an <itemizedlist>. So I created a script takes the selected text and creates an <itemizedlist> by splitting the text up where ever a comma appears.

I use TextMate for my editing and write scripts for it using ruby. Many of my colleagues use gedit so I have also created a gedit version. There are no instructions here on how to set these up in your editor, that is an exercise left up to the reader.

As an example:

publish, security, subscription, subscription-listener, and interface 

is turned into

    <listitem><para>and interface</para></listitem>

Note that it relies on the use of the serial comma to get the last item and doesn’t remove the “and” from the beginning of the last item. I have kept each <listitem> on a single line for neatness because the use-case for this script usually involves the items in the list being single words or very short phrases.

The gedit snippet

Note that this is Python, so the white space at the beginning of lines does matter.

tab = "    "
joined = ""
output = "";

for line in text.split("\n"):
  line = line.strip()
  joined = joined+" "+line

for item in joined.split(","):
  item = item.strip();
  if item != "" :
    output += tab+"<listitem\><para\>item</para\></listitem\>\n";

return output;

TextMate command script

#!/usr/bin/env ruby -w
tab = "    "
joined = ""
text.each do |line|
	line = line.strip
	joined = joined+" "+line

puts "<itemizedlist>"

joined.split(",").each  do |item|
  item = item.strip
  if item != "" then
    puts "#{tab}<listitem><para>#{item}</para></listitem>"

puts "</itemizedlist>"

Cross-posted from: http://shinysparkly.com/blog/2010/02/12/turning-a-comma-seperated-list-into-a-itemizedlist/

Why Thank You!

November 13, 2009 by

Yesterday, a co-worker alerted me to the fact that my name had been listed as one of the Top Open Source Technical Writers on the web. I was blown away! I am seriously over the moon about it all, and wanted to sincerely thank both Aaron Davis and Scott Nesbitt of DMN Communications for the vote of confidence.

Technical writing is a funny kind of industry to be in. The people who are in it are for the most part seriously excited about where tech writing is going, and what we can do along the way. Of course, combined with the type of people who are involved in open source generally, it means you end up working with crazy-smart people who are really seriously passionate about what they do, and how what they do can make the technical world a better place.

I’m very privileged to be able to write free/libre and open source technical documentation for a living. Not many get to have that experience. The things that the open source community has taught me, and the experiences I’ve been able to have doing so, are something that working anywhere else just wouldn’t offer you.

My passion is creating the best technical documentation I possibly can, and making it available to as many people as possible. More often than not in open source, the deadlines are tight, the scope is big, and the resources limited. The challenge that situation creates is, as expected, pretty huge. Being given the opportunity to attempt to create documentation that shines within that environment is one of the biggest challenges I’ve ever encountered. It’s a challenge that I wake up every morning to, and while there are days that I think I can’t do it, there are many more days where all I want to do is inch a little closer to that goal. Having people like Aaron and Scott publically recognise that effort is what makes the hard work all worth it.

To follow on from Aaron and Scott’s list, I’d like to shout out to all those people who write, contribute, edit, review, and use open source technical documentation – even if it’s only spotting typos and raising a bug. You are the ones who deserve the recognition, because without you, I wouldn’t have the opportunity to do what I love. I hope you all enjoy creating and using open source technical documentation as much as I do.

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

Building Publican DocBook Projects in Maven using jDocBook

November 5, 2009 by

Situation: I have a Docbook project that builds in Publican. However the same book also needs to be able to be built by a different team using Maven and jDocbook. How do I make this happen.

1 – You’ll need a Maven POM (pom.xml)

Publican 1.0 currently no longer includes POM creation. The previous generation of Publican, ie 0.45 and earlier, would produce a Maven POM (pom.xml) with the command make pom. Either generate one with a pre-1.0 version of Publican or make a copy of a pre-existing one.

2 – Add the jboss.org Maven repository configuration to the POM
The POM produced by Publican lacks the repository configuration to actually make it work.

EDIT: Apparantly this is because users were being instructed to add this configuration to their ~/.m2/settings.xml. In my opinion this is counter to the design of Maven. Projects should be self contained and not rely on local configuration.

The missing sections are:

        <name>JBoss Repository</name>

        <name>JBoss Repository</name>

These are the repositories that contain the jDocBook Maven plugins as well as the default JBoss style plugins. Just add this XML to the POM within the scope of the <project> tag, e.g. just before the <build> element.

3 – Make sure the POM matches the book.
If you didn’t use Publican to generate a new POM and are reusing a POM from another project then the <properties> section will probably not match your book and will need to be edited.

     <bookname>A User Guide</bookname>

<docname> needs to have the same value as the file name (minus the .xml) of the starting XML file of your book, i.e. the one containing the <book> or <article> element.

<bookname> is only used in the <name> element of the <project> … and nothing in this POM makes use of it, so it doesn’t really matter what you put here. I’d set this to whatever the title of the book is.

4 – Add entity declarations to the top of each of your XML files.

Publican enforces some good habits, like having all your entities declared in one file. However entities actually need to be declared in every file that they are referenced from. Publican as a part of it’s “pre-build” process inserts the declarations into each file for you. jDocBook doesn’t do this however so you need to add a reference to your entities file (A_User_Guide.ent) in the header of every XML file that uses those entities. If you don’t do this, the entities will not populate in your book.

<?xml version='1.0'?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

Note Publican is smart enough not to duplicate this during its own build process.

4 – Specify both role and language for <programlisting>

In Publican, to make use of language syntax highlighting in <programlisting>, you specify the attribute language with the value of the language that the <programlisting> contains. This is actually the correct behavior according to the Docbook specification.

<programlisting language="xml">

However the underlying highlighting library that jDocBook uses requires that the language be specified with the attribute role.

<programlisting role="XML">

You can simply specifying both attributes so it works in both systems.

<programlisting language="xml" role="XML">

Note that Publican requires the value to be lowercase, and jDocBook requires it to be uppercase.

EDIT: For Publican 1.0, the capitalization of the language value needs to match the LANGUAGE column athttp://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS.

That’s the easy stuff. Dealing with Publican’s Common Content is a little trickier. In many cases you can simply supply a Feedback.xml, Conventions.xml and Legal_Notice.xml to satisfy the fallbacks. But that isn’t really a good long term solution for a couple of reasons which I’ll deal with that another time.

Maven will build this book with the command mvn compile. The Publican supplied POM will build html, html-single and PDF versions of the book using the default JBoss documentation styles.

If you do not want to use the default JBoss documentation styles then you will need to create your own jDocBook style Maven plugin. This isn’t terribly difficult but is also a topic for another time.

Cross-posted to: Oh Look A Shiny Sparkly Thingy!

Magic waterfalls

October 20, 2009 by

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 by

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 by

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 JBoss.org 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.

The beast within

September 16, 2009 by

Writing is the only thing that, when I do it, I don’t feel I should be doing something else.

Gloria Steinem

National Novel Writing Month (NaNoWriMo) is coming up again. And so, like many other writers (both professional and aspiring), I’ll be setting aside the thirty days of November to pump out 50,000 words of a novel, or about 1,600 words a day. This is in addition to the thousands of words I pump out every month as part of my role as a technical writer, of course. The question here is, what on earth makes someone who writes all day for a living, want to go home and write all night as well? It sounds like a Dr Suess story: “Oh I say, we write all day. Write, write, we write all night”. The really peculiar thing is that I’m not alone in this endeavour. There are many tech writers out there moonlighting as novelists every November. Don’t try to take a tech writer out to dinner in November, unless you’re willing to have them with their laptop out at the table … taptaptaptappitytap


I suspect writers are born, not made. That’s not to say that good writers are rare, I actually suspect that they’re quite ubiquitous. Many of them never actually become writers. They become all manner of other things – butchers, bakers, and candlestick makers – but that drive to write exists within them still. They might write a private journal, be secretly working on a novel, submit letters to the editor, write lengthy letters to their friends, submit stories to a website, or keep a blog.  Or just wish they had the time.

All of this means that, as a writer, when you meet another in the street, you see that gleam in their eyes. There’s a passion, an excitement, a certain joie de vivre that they only truly experience when they are head down and writing. Have you ever wandered down the street, completely lost in thought trying to work out a plot twist, a character development, a particularly witty piece of dialogue, only to realise that you’re grinning your head off, looking like a loon? Then you’re a writer. And here’s my advice to you: don’t fight it.

I have a stack of manuscripts in my desk drawer. Will I ever submit them to a publisher? No. Will I ever give them the edits and re-writes they really need? No. Will I ever look at them again? Probably not. So why bother creating them in the first place? Because I need to write. There is a living thing inside me that is only satiated when there are words flowing through me. What happens to those words afterwards is entirely irrelevant. I think them up, I write them down, I make sure I like the way they sound, and then I let them live on without me.

So if you share my passion, why not join me in November? And if just one month a year of crazy writing isn’t nearly enough, why not apply for a job?

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

Red Hat Enterprise Linux 5.4 Technical Notes – “Every Change to Every Package”

September 2, 2009 by

We’re getting ready to push the new “Technical Notes” document to redhat.com/docs for Red Hat Enterprise Linux 5.4.

The Technical Notes document, new for this release, contains errata documentation for every single change to every single package between Red Hat Enterprise Linux 5.3 and 5.4. In the six months between releases there have been more than 2000 changes to more than 250 packages; and every one of them has been documented for this release in a document that, at 500 pages, is the length of a short fantasy novel.

This document has been the work of a number of authors, led by Ryan Lerch, the Technical Notes author, and Brian Forte, the Red Hat errata queue maintainer. It’s also involved the collaboration of engineers throughout Red Hat, processes, and automation.

Update: The Technical Notes are now live on redhat.com. You can view them here.

Creating technical documentation in five easy steps

August 7, 2009 by

Writing a book is an adventure. To begin with it is a toy and amusement. Then it becomes a mistress, then it becomes a master, then it becomes a tyrant. The last phase is that just as you are about to be reconciled to your servitude, you kill the monster and fling him out to the public.

–Winston Churchill


Step 1: Planning – who is the audience? What are the book’s goals?

Step 2: Content – what are the chapters about? Where will you get the information?

Step 3: Writing – first draft, review, second draft …

Step 4: Internationalisation/Localisation – will the book be translated? Into what languages?

Step 5: Review – what worked? What didn’t? How will the book be maintained?

Read the rest of this entry »

Planning and flow

July 22, 2009 by

After a considerable amount of struggle, I have managed to beat SELinux/rsync/Fedora 11 into submission and my chapter in managing-confined-services about running rsync on a non-standard port is just about done.

Start with properly labeled files to share (public_content_rw_t). Create a custom init script from scratch to launch rsync as a daemon as there is none shipped in the F11 distro. The script itself needs to be properly labeled as initrc_exec_t so that the rsync daemon will launch as rsync_t. If the rsync daemon doesn’t transition to this, the related Booleans (or SELinux itself) can’t be expected to have much of an effect over rsync.

So, we have a daemon in the rsync_t domain. Modify rsyncd.conf so it has a non-default port directive, which looks something like port = 10000 (in the global section of the file). Now, after starting rsync from the new init script again, SELinux will not at all be impressed that rsync has started on a port that it doesn’t expect (ie. a port that is not defined in rsync_port_t). Give up now? Never! Run:

# semanage port -a -t rsync_port_t -p tcp 10000

Still with me?

That command will appease SELinux (fussy little thing, huh?) and rsync will happily start on 10000.

This has been a pretty long battle to distill all this information from disparate sources online, IRC support channels, mailing lists and of course good old-fashioned google-fu. The world of SELinux can be quite arcane and this book is unique in that it covers real-world examples of how to enable services an administrator might configure and how to work around the problems that are commonly encountered. Let’s just say I kept finding my own book in google when searching for solutions!

Once I had all the details gathered it was a pretty quick task to get it all in XML, ready for proof-reading and minor editing. It’s become apparent to me that depending on your subject, perhaps you won’t spend so much time actually writing. This rsync adventure required a working lab setup, fully tested and confirmed and repeated before I even opened a para tag. Have everything ready, research your subject, make sure you have at least a decent outline and some sort of progression of how it will look, and the actual flow of information tends to go pretty quickly from then on.