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

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:

<repositories>
    <repository>
        <id>repository.jboss.org</id>
        <name>JBoss Repository</name>
        <layout>default</layout>
        <url>http://repository.jboss.org/maven2/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <id>repository.jboss.org</id>
        <name>JBoss Repository</name>
        <layout>default</layout>
        <url>http://repository.jboss.org/maven2/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

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.

<properties>
     <translation>en-US</translation>
     <docname>A_User_Guide</docname>
     <bookname>A User Guide</bookname>
</properties>

<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" [
<!ENTITY % BOOK_ENTITIES SYSTEM "A_User_Guide.ent">
%BOOK_ENTITIES;
]>

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!

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

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.

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.

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

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.

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?

This is a very distilled version of JoAnn Hackos’ method. It all seems very easy doesn’t it? It’s a fairly logical progression through the steps. Writing in general is often considered an art, a talent (you either have it or you don’t), a skill, and somewhat mysterious and unique to a small portion of the population. In fact, writing is something that many people can do, and a lot of people can do well. Where it gets difficult is the same place as where any task worth doing gets difficult – sticking with it. Writing is not something you can start on Monday, and have a completed book by lunchtime on Thursday. This goes for technical writing as much as any other style, and it’s where the apparent ‘magic’ comes in. Some people have the ability to sit in a small room on their own for weeks at a time, taking and distilling technical minutae by day, and sipping absinthe by night until – like a miracle – they give birth to a brand new shiny technical manual. And some people … well, some people just don’t. Which is not terrifically surprising, on the face of it.

The idea of writing a book is romanticised in our culture. Everyone ‘has a book in them’; we’re all trying to write the ‘great American/Australian/British/$NATIONALITY novel’; one day, I’ll ‘be the next Hemingway/Dickens/Crichton/$AUTHOR’. How many people have started on the path, only to find – days, weeks, months, or years later – that it has been consigned to the desk drawer, and forgotten? This all leads us to believe, however subliminally, that writing a book is hard. It takes a long time, it is terrifically difficult, and only a bare few make it out the other side. It makes us feel better about the unfinished manuscript in the bottom drawer.

Which leads us to realise why so many versions of the writing ‘process’ exists. If you google for it, you will be spoiled for choice in the methods available. It’s a way of breaking down the mammoth task of creating a book into small, manageable, easy-to-chew lumps. Somehow, five (or six, or seven, depending on the method you choose) small steps aren’t half as scary to tackle as one big one: “Write a book”.

When it comes to technical writing, though, the process has more purpose. Technical documents are very rarely produced in isolation. The book could be part of a suite of documents for one product – the Installation Guide, the User Guide, the Reference Guide; it could be a guide for a product that forms part of a complete solution – the front-end tool, the back-end database, and the libraries; it could simply be a book produced by a large technical company that produces a large range of products. Whatever other books or products compliment the work in progress, there needs to be a consistent approach, a ‘look and feel’ that creates a brand around the product. By following a standard process for each and every book written, that brand is more easily created and maintained, even by many authors, all working on individual projects, and in their own unique ways – absinthe or no absinthe.

Cross-posted at On Writing, Tech, and Other Loquacities.

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.

Writing gives you the illusion of control, and then you realize it’s just an illusion, that people are going to bring their own stuff into it.

- David Sedaris

Technical writing is a strange breed. When you write fiction or poetry or a screenplay, it’s a release, it’s a way of expressing what is inside yourself, and allowing your imagination to creep into the those little crevices in your brain, and poke about to see what squirms. Writing technical documentation is almost entirely the opposite. It’s about getting into the heads of your readers, finding out what makes them tick, how they work, and then presenting them with the information in a way that will make them go “Aha!”. It’s about taking source documentation that would make your eyelashes curl, and crafting it – shaping it, massaging it, chewing it up and spitting it out – into something that not only makes sense, but is useful, intuitive, and – dare I say it – beautiful.

Beautiful technical documentation? Why yes. I think so. Bad technical writing is hard to use, hard to understand, and hard to find what you want. Good technical documentation is intuitive, easy to navigate, and aesthetically pleasing. Good technical documentation is beautiful.

The question, then, is how to create beautiful technical documentation, and how to know when that’s what you’ve got. While it would seem easy to tell when you haven’t got it, it is not always as simple as it might sound. The problem is the same as a lot of artists and craftsmen complain of – getting too close to the subject matter. One of the reasons that engineers can not generally create effective documentation is because they get too close to the nuts and bolts of the thing. They spend too much time looking at the engine of the beast, that they become unable to describe what colour the paintjob is. That is where the documentation team step in – we bring fresh eyes to the project, and are able to look at it from the top down. We can describe what it looks like, what it does, and how to do it, without having to explain how that happens. But once you’ve been working on that single document for months, you’ve been through revisions, and revisions of revisions, you’ve been bombarded with information from the technical team, you’ve had requests for more detail, more depth, and more minutiae … then how do you tell if it is any good? Your advantage – your fresh pair of eyes, your ability to see the big picture, and your talent for information organisation – is no longer whole. Now you are the one who is too close to the project.

A writer of fiction would tell you this: put the book down, step away from the desk. Leave it for a week or two, a month or two. And then tackle it with fresh eyes. A technical writer would scoff – who has time for all that? This book needs to be released next Wednesday!

Often, the solution is to hand it to someone else – a fellow writer – for review and comment. But what about when that option isn’t available either? Every writer has their own method of handling this. What I do is this: I put it down, not for long, but for an afternoon, or overnight. And I write something else. Something completely different. A blog post, for example, or a chapter of a novel, or a short story. Anything that has absolutely nothing in common with the piece you’re working on. Ensure the voice that you are writing in changes, the topic changes, the emotion changes. Then, make yourself a cup of tea, and pick the book back up again. But don’t start at the beginning. Read it backwards. Read each page, on its own, in reverse order. I even read the paragraphs in reverse order. Start at the last one, and work your way back to the beginning of the book. You’re checking for typos, for sentence structure, for punctuation, grammar, and all that good stuff. By reading it out of order, you’re less likely to drift off and start thinking about something else. You’re more likely to read what’s there, rather than what you think is there.

Then find a blank piece of paper. Put yourself in the mind of your customer: What do they need to know? What are they trying to achieve? Why do they have your book? The answers will be myriad – but list the obvious ones out. You need to think about what your customer knows, and what your customer doesn’t know – that gap is where your book fits.

Once you’re thinking like a customer, pin that list up somewhere you can see it, go back again, and read the book in order. If you’re able, read it aloud, it helps to catch odd phrasing. This time, you need to be looking for flow. Make sure each paragraph flows into the next, that each section flows into the next, that each chapter flows into the next. Check that you’re introducing concepts in order from the top down – start with the big things, and then explain the detail as you go on. Cut out anything that doesn’t fit. Don’t be afraid to cut and paste paragraphs, to taste-test them in a new arrangement.

And the whole time – there’s only one thing you should be thinking about – your customer. If the customer perceives value in your documentation, if your book bridges that gap between what the customer knows, and what they need to know – then they will see the beauty in it.

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