Over the last few weeks, I’ve been thinking about and using markup languages quite extensively. Not the markup languages that you normally associate with documentation — like HTML, XML, or even LaTeX. I’ve actually been doing some work with lightweight markup languages, specifically one called Markdown. My focus has been using Markdown to write articles and blog posts (including this one); you can read more about my adventures with Markdown here.
Monthly Archives: January 2008
Can lightweight markup languages be used for documentation?
Topic oriented authoring: a visual analogy
Further to my previous post on whether or not DocBook is dead, Norm Walsh has an interesting and detailed comparison of topic-oriented and narrative style documentation. He uses a very interesting analogy: Van Gogh’s painting Starry Night. You have to read the posting and see the accompanying graphics to fully grasp the analogy.
Walsh makes an interesting point in this post: writing topic-oriented documentation isn’t as easy as it sounds. That’s not to say that you shouldn’t try it, but don’t expect it to be smooth sailing or the panacea to all your documentation ills.
Is DocBook dead?
You don’t hear that much about DocBook these days. It seems to have been overshadowed by that younger, more glamourous upstart named DITA. I’ve even heard rumblings that DocBook is dead, or at least on its last legs.
While DITA has become a cause celebre in the technical communications world, I don’t think that you count DocBook out just yet.
Web screen shots, with a twist
Scott Abel has pointed out a interesting online screen shot tool. It’s called Kwuot, and it enables you to not only take screen captures of a Web page, but also keeps the hyperlinks on those pages active. Yes, you can click the links in the image. And Kwuot is really easy to use.
You can read Scott Abel’s writeup here.
Podcast for the week of Jan. 7, 2008
The podcast is back after a few hectic weeks away. In the next while, we hope to get back into something resembling a regular podcasting schedule.
To whet your appetite, this week we’re presenting an interview that Aaron did at DocTrain West 2007 with Emma Hamer. In it, Aaron and Emma discuss content management.
You can listen to the podcast here.
Striking fear into the hearts of users everywhere
That’s the impression that I got when I read a blog post titled “Greatest error message ever?” Take a peek — the error message highlighted in the blog post is funny and creepy at the same time.
How would you have written this error message? Feel free to leave a post.