On DocBook versus the rest

I must say I have tried them all before and if its technical documentation you need to accomplish, try out docbook. Instead of writing out a separate piece I thought it best to place some thoughts I shared with my team on this subject.

Well, to start with, on the subject of documentation, the situation is hardly picture perfect, so we need to shape up on that effort. From another perspective, it is known to each one of us that documentation is not easy, there are issues of language, style, technical comments and so on which need to be considered on top of which comes the painful part of ensuring consistency in presentation and style. All of this makes for a heady mixture, which usually results in the activity being relegated to the back of our minds. Therefore, while we must document more we must also find a relatively easier way to document. Docbook is an effort in that direction.

Now without going into an elaborate explanation, I would like you to get cracking from the word go, so please access the following link (I thought this was a good starting page, there are hundreds of references on the Internet) and go through the tutorial, its self-explanatory and unbelievably simple.

http://opensource.bureau-cornavin.com/crash-course/index.html

Therefore, the next time you are responsible for working on any installable (be it an installation or tool or other user interface dependent software application), end user documentation will be a must. You should document what you intend to communicate to the end user unambiguously. A potential process is described below [I am open to suggestions on improving this as we start developing this]

1. Create a separate document folder along with any installable which is going to be used by a end-user with the distinguishable name.
2. Create a document with the extension “.docbook” to indicate you are preparing a docbook format file. Put in all the relevant information you want to put using the set of tags applicable to the document you are preparing.
   
3. Commit the docbook to source control after a review
4. Send the document to specialized documentation expert (if applicable) for actual conversion to desired formats. Currently, docbook supports and we have tested with html (multipage only tested, single page should be available but we have not tested it), PDF and RTF from the same source docbook file.
5. Documentation team (if applicable) will then convert it and hand it back to you for final distribution as desired. The conversion itself will not take too much time if you have prepared the documents with a reasonable structure in your mind, so please try to ensure that you keep the document simple for easy and quick conversion.

Thats it, you are pretty much done, you can maintain only your docbook format under source control and the rest are mere formats for external communication.

From Slashdot to Blogspot

I dont recall exactly howI got the nick Slash (nothing to do with the famous guitarist for sure) but anyway helped to put up an interesting title for this post. So yes, I got hooked to Slashdot way back in the mid-nineties and while the interest hasnt waned certainly the posts have become more complicated by the day (yeah yeah I am getting to be a ignoramus). OK so what did I want to say here, yes I wanted to simply say that its been a long journey of a few years getting from reading posts and articles by others (all moderated by the Slashdot team of course) to where I find myself today, with no editorial control over what I want to say thanks to blogging.
This blog is dedicated to news and views of interest from the world of Information Technology (IT) and it is hoped will function if nothing else as a bunch of useful links and some views on my own experiences with software and software development over the course of the past two decades or so that I have been associated with computers.