January 28, 2011

Mark-up Smackdown

In the tradition of old is new mark-up languages are making a serious comeback for professional technical documentation. In the dark ages troff and other *roff variants ruled the roost. As more writers moved into technical writing and computer graphics got more powerful WYSIWYG tools like FrameMaker and Word rose to prominence. Now the pendulum is swinging back to mark-up.
Markup languages come in two basic flavors: presentation mark-up and structural mark-up. The difference is that presentation mark-up is focused on how the text is presented and structural mark-up is focused on the structure of the content. The difference is subtle but important.
Focusing on presentation, as most current WYSIWYG editors do, tend to favor a particular presentation medium (the Web, print, slides). While the presented content appears to have a structure because it has headings and lists, etc. the underlying source has no real structure. A writer is free to use lists and headings in any way they wish. This is nice for. Writer, but makes content reuse more difficult.
Focusing on structure removes the preference for any one particular presentation medium, but it does mean that more work is required to transform the source content into a presentation medium. The underlying source has an enforced structure to which a writer must adhere. The enforced structure is limiting, but allows for easier reuse.
Among the popular current presentation mark-up languages there is a pretty consistent preference towards Web presentation. Along with HTML there are a number of wiki mark-ups in use including MediaWiki, Confluence, and MoinMoin. There is also Markdown and Textile. They all attempt to make it easier to craft good looking content on the Web. To a high degree they all succeed. I personally like Textile and Markdown because they allow the writer to mix in HTML code to fill in gaps left by the mark-up language. The draw back to all of these languages is that they do not replicate all of the functionality of HTML and their syntaxes can be fidgety. If you don't do it exactly right the resulting output is bad and there are no good tools to help you get it right.
In terms of appropriateness for large technical documentation projects, presentation languages have serious drawbacks that counteract the oft touted claim that they are way easier to use than the alternatives. Because they leave structure up to the writer and the base unit of content is a page, it is difficult to recombine content or enforce uniform structure across a documentation set. They don't generally provide tools for indexing content or thinking of organizing content beyond a single page. They also don't have easy translations into any other presentation medium than HTML.
Structured mark-up languages, such as DocBook and DITA, push concerns about presentation into backend processing stages. The mark-up itself deals with content structure. They have enforced concepts of what makes up a unit of content. DocBook uses structures like chapters and sections. DITA uses structures like procedures and reference topics. These units of information are easily combined into larger structures like books and libraries. The drawback for some writers is that there is no easy way of seeing what the content will look like when it is published. A lot of people find it easier to write when they can see a representation of the final product and feel like they need control over the design of the content on the page. Another drawback is that structural mark-up tends to be more complex than presentation mark-up. The learning curve is steeper, but there are a numbered of tools available that support content completion for DocBook and DITA.
For large scale documentation projects structured mark-up, despite its steeper learning curve, has the edge over presentation mark-up. The freely available toolchains for them provide translation into Web and print formats. They have indexing mechanisms and provide structures to support content beyond a single page or unit.
The presentation mark-up will continue to be good choices for content developed by small teams or developers. For big projects down by professional teams, structured mark-up i the future.

January 14, 2011


I recently read an article by one of those magazine shrinks that said that the important part about new years resolutions isn't keeping them; it's making them that matters. The process of making resolutions forces you to imagine how you would like your life to be different and imagine actions you can take to make the dream real. The more specific the resolutions the better.
Since it is that time of year, I'm going to take the article to heart and make three specific resolutions; one for work, one for family, and one for me.
For work I resolve to work as part of a team that accepts nothing short of excellent. Far to often we settle for doing the minimum because of resource constraints or we accept crappy user interfaces because the developers know best. This year I resolve that I will strive to do what is needed to provide the maximum benefit for the end user. I will not simply accept good enough. I will not sit idly by when a developer creates a bad UI or tries to slip a buggy feature into a release because it is good enough or there isn't enough time to fix it.
At home I resolve to do more around the house. I have a bad habit of putting off washing the dinner dishes until H just does them. I also tend to let laundry sit without being folded. In the warmer months I'm not great at keeping up with the yard work. This year I will be better about getting this stuff done.
For myself I resolve to take better care of myself. This includes flossing every night, doing something active at least three times a week, and eating better. I'll think twice before stopping at the McDonalds for a super size Big Mac meal. I'll actually order non-fat lattes. I'll eat more veggies. I'll actually start using the gym at work.
I want to be around for Kenzie for as long as possible. I also want to be a good role model for her. I want her to grow up seeing her dad living a healthy lifestyle, treating his partner with love and respect, and striving to be the best the he can be.
I know I'll fall short of these resolutions, but I will try to get closer to living my life according to them.