Building Publican DocBook Projects in Maven using jDocBook

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.

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!

Magic waterfalls

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

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.

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

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”

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

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?

Planning and flow

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.

Crafting beautiful technical documentation

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

All the world’s a stage, and all the men and women merely players

In what has become a somewhat impromptu series on the evolution of the English language, I just had to mention something I read whilst on holidays last weekend. I picked up Bill Bryson’s take on the life of Shakespeare whilst away. I’ve been interested in the great mystery of Shakespeare’s life for some time now. I own a copy of Nolan’s “Shakespeare’s Face” and have read numerous other accounts (or, more accurately, guesses) of his life and works. Add to this the fact that I have been wanting to start reading Bryson’s “A Short History of Nearly Everything”, and it was a fairly predictable attraction. Not incidentally, I’m intending to read his “The Mother Tongue” shortly too.

The book is quite short, and I finished it mere days after purchase – helped along by a few days in a warm climate with no pressing demands, I might add. It is written in true Bryson style, very conversational and light hearted, and he gives a lovely (or not so lovely, depending on your take on plague and wanton violence) picture of 16th century England, and Shakespeare’s somewhat unassuming – so far as we can tell – place in it.

However, my favourite part is this discussion of some of the many words that Shakespeare (allegedly) introduced into the English language:

And there was never a better time to delve for pleasure in language than the sixteenth century, when novelty blew through English like a spring breeze. Some twelve thousand words, a phenomenal number, entered the language between 1500 and 1650, about half of them still in use today, and old words were employed in ways that had not been tried before. Nouns became verbs and adverbs; adverbs became adjectives. Expressions that could not grammatically have existed before – such as “breathing one’s last” and “backing a horse”, both coined by Shakespeare – were suddenly popping up everywhere. Double superlatives and double negatives – “the most unkindest cut of all” – troubled no one and allowed an additional degree of emphasis that has since been lost.

Bryson goes on to mention the notorious variability of spelling known in early English society, noting this little gem -

Perhaps nothing speaks more eloquently of the variability of spelling in the age than the fact that a dictionary published in 1604, A Table Alphabeticall of Hard Words, spelled “words” two ways on the title page.

Of course, it just goes to show that the language has been evolving apace for many hundreds of years. Indeed, despite the naysayers it is happening much slower now than it was back in Shakespeare’s day. I can imagine that back then there were people (perhaps among the upper, educated, classes) who complained that artists such as he were mangling the language, and doing things the wrong way, although the attitude towards English was reasonably fluid then, thanks to Latin and French being considered ‘proper’. Surely, as time went on, and English took hold first in business and legal matters, and later in the sciences, that there have been people unwilling to accept change, even as it occurs around them. Nothing has changed in that respect, I imagine, it’s just that now they have access to the internet – and a world full of people reading their opinions. Hopefully, it won’t impede the progress overly. Much as I still cringe a little at “truthiness”, “coopetition” and “incentivise”, I am completely capable of embracing the words that I like – “blogosphere” is one of my favourites, along with “jumping the shark” and “backronym”. It’s only a matter of time before the language evolves to the point that our grandchildren will be almost incomprehensible, and Shakespeare’s scribblings will have taken another step towards total obscurity.

Originally posted at On Writing, Tech, and Other Loquacities