Can lightweight markup languages be used for documentation?

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.

Continue reading

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.