Prediction: 2009 will be the year of documentation

2009 is shaping up to be the year of documentation for me. This is what I've got planned so far:

  • Front End Drupal launches in April (pick up a copy of Using Drupal in the mean time -- the two titles go together like kittens and yarn).
  • I'm volunteering with the Ubuntu and Drupal documentation teams.
  • Lynda and I are planning to completely revamp my client documentation into works that are beautiful and usable and inspire people to overcome their fear of technology.
  • the world's first-ever (as far as we know) conference dedicated entirely to open source documentation (and other learning aids). More news soon.

And it's only January!

One of my projects for this year, both personally and professionally, is to make documentation look better. Yes, I'm working on the content as well. But I really want to improve the visual design of information. I want documentation to be pleasurable to look at. No more crappy Word documents with default fonts and ugly margins. No more low-quality screen captures. No more icky. One of the first steps to solving this problem is working to improve existing documentation. I'm tackling the hardest stuff head-on--print documentation. In the days of Web 2.0, the Kindle and 140 character twitter updates, print documentation has been falling out of fashion. But in a lot of cases print books still make sense and when they do make sense I want them to be worthy of your time.

So with a lot of help from my notes on DocBook, Fyodor (go buy his book on Nmap it's AMAZING) and Google I'm working on the intricacies of XSL transformations. In about 24 hours I've created a new style sheet that will eventually be open sourced for everyone that wants to publish their own beautiful documentation. The idea comes from some of my favourite open source authors who are goin' out on their own and publishing their own books (I think traditional publishing is good too, I just want to do what I can to make alternatives possible to a wider ranger of authors).

For comparison I've converted the Ubuntu Server Guide using the current Ubuntu style sheet and the new one. They are very minor changes and some are comparing apples to oranges. For example: the current style guide assumes you are going to read the documentation in PDF format on-screen. Many of the enhancements I've added are to make a printed book instead of an on-screen PDF. The current templates are completely fine (and a LOT better than a lot of others that I've seen), but I want to do better than that. Let's take a look: 

sg-compare-inner  sg-compare-chaphead

You'll want to click through to see these up close. Here's a few features though:

  • chapter name, chapter number and section names in the header on the insides of the pages, and page numbers on the outside of the pages (adapted from many fine technical publishers);
  • colour headings (I haven't spent a lot of time with the colour, this was more of a proof of concept);
  • table of contents at the beginning of each chapter (and chapters always begin on a "right" side/odd numbered page);
  • on chapter headings the page number is in the footer;
  • end of line hyphenation.

To make the newly styled PDF I'm using free tools and a lot of free resources. In fact I am so appreciative of the DocBook and the DocBook XSL resources that I plan to buy both of the print books. At least once. I'm using Apache FOP from svn (the current version in Ubuntu throws up errors on transparent PNGs), xsltproc and vim. There are also excellent tutorials that I've found including:

I'm also looking forward to helping out with translation teams. I don't know a lot about the requirements for printing documents in languages other than English (and maybe un petit peu de Français), but I'm planning on figuring out diacritics in PDFs. If you're keen on making 2009 the year of creating awesome documentation and learning tools please head on over to the Drupal Documentation project, the Ubuntu documentation project, or even your local library's adult literacy program. We'll need all the help we can get!

"the world's first-ever (as

"the world's first-ever (as far as we know) conference dedicated entirely to open source documentation (and other learning aids). More news soon."

When / what / where?? How can I help?? XD

I am signed up to go to this: http://www.writersua.com/ohc/index.html and I'm sure it would have a lot of stuff I could learn, but going to an entirely open-source doc conference would be way cooler.

I'm interested in that

I'm interested in that conference too... please share the news!

I'm also interested in hearing your thoughts on Empathy documentation. I'm trying to write it, but it's a tough task. I've been writing Brasero one and helped a little bit with Seahorse, but Empathy is a total different project and complex too. If you want, drop me an email.

Cheers.

Woohoo! Congrats on your

Woohoo! Congrats on your book getting closer to the finish line. That will indeed mark this year as a good year. Great info on the design of docs you are doing. Definitely something I want to learn more about (and inject into Drupal docs this year). The redesign of Drupal.org should give us more flexibility for online docs, but getting nice references into other formats would be a nice target for the year as well. Glad to have a handy expert "on staff" that I can turn to. ;-) I'm also quite excited about our conference and can't wait 'til we start shouting out a bit more about it. This will definitely be a year for rockin the doc.

(via Planet Ubuntu) Southern

(via Planet Ubuntu) Southern Ontario represent!

A couple of comments: one, for online documentation, Sphinx (as used by Python) surprised me recently, but is really very beautiful and easy to use.

The other arises from being an engineer who uses LaTeX frequently. I really appreciate the effort that has gone into making LaTeX output typographically beautiful by default, including:

  • shorter lines (~10 words or 70 characters),
  • larger leading and tracking, and
  • hyphenation.

I have nothing against DocBook, XSL and FOP, but I have seen (and made myself!) a lot of FOP output with very long lines, tiny text and so on which becomes painful to read very quickly. The "new XSL" is nice but still has some of these problems. I don't mean to suggest that you change your toolchain, but there are lots of things (multiple columns, wide margins, bigger type, hyphenation) that could be done to make documentation that is super readable.

Props for giving

Props for giving documentation the love it so needs. =)

Oh, thanks for this article!

Oh, thanks for this article!

I'm also writing in Docbook currently, and the PDF output just doesn't look good :/ (well, the HTML one looks like Web 0.5 too, but Print is worse). I'll check out your links in the hope of learning enough about FOP to improve our stylesheets :)

Git for Teams

Git For Teams

Best selling title from O'Reilly media. Covers essential skills needed to use Git in a team environment.

Available from O'Reilly media, and better bookstores worldwide.

Collaborating with Git

Collaborating with Git

Practical how-to videos to get you, and your team, up and running with Git. A complementary video series for the book, Git for Teams.

Available from O'Reilly media.

Drupal User's Guide

Drupal User's Guide

Site building for Drupal 7. Includes in-depth information on Drupal's most popular site building modules, SEO and accessibility. Two complete case studies are included in the book along with the tools you'll need to build (almost) any Web site with Drupal.

Available from Amazon.com.

Front End Drupal

Front End Drupal

The industry go-to for learning theming in Drupal 6. A great companion to Lullabot's book, Using Drupal.

Available from Amazon.com.