My pre-release relief

So, it's nearly done. CDT 4.0 will be out the door with the rest of the Eclipse 3.3 goodness and all I can say is, whew.

This release marks the first time I've publicly contributed to the Eclipse movement, the first time I was able to look beyond my cube and the work involved there in shipping Carbide.c++ and really try to make some difference with the tools we've been using as the basis for our product every day for the last 2 years.

And it wasn't for lack of desire, just time and energy.

When our group came to Nokia we were using an aging code base for a proprietary product, who's interface was not well liked by our customers due to its different design origins. It was also a pain to add features to as its support for multiple architectures, operating systems, compilers, etc. had made it somewhat fragile over the years. We wanted to get away from that tool and into something different, and the something different we settled upon was Eclipse and CDT.

Some of the things that made the switch appealing was the fact that we could improve and add features quite easily, and generally work to solve our customers problems with less fear of "breaking" another product. Whereas in the old days we tentatively worked to add a feature here and there, it was always done carefully and with trepidation that something would surely break. However, with Eclipse it was "how can I add this feature, let me count the ways" versus "good grief, how do I add this feature without breaking everything. The shear scope of the flexibility was empowering. It was not without some learning curve though.

On the docs side of the house the entire process for producing and contributing docs changed. How they were organized, updated, and maintained changed. Its been a rollicking time learning, growing, and expanding my knowledge in this area, and hopefully helping others in the company expand theirs as well. Since several groups within Nokia were moving to Eclipse it was somewhat heartening to know that the problems I had investigated and solved last month could be passed on to others to help solve their problems too. Progress has been both rapid and the improvements many as each release went out the door.

Once our last product release was final, I felt it was time to contribute some docs help to the Eclipse and CDT communities so that everyone in the community could benefit, not just our customers. Docs are always the last thing people think of to do and are as we all know, not an engineers favorite part of the project, so being able to assist in this area is pretty rewarding. Doing so addresses a critical component of the release, it makes the release look more like a polished product, and hopefully, helps us garner a few new members to contribute in the future.

Its been a great time so far and I am now seriously looking forward to the next release and what can be done with the docs in the interim.

My 3 rules of technical writing

When writing technical document, especially for busy software engineers, the three rules I follow include:

1. Keep it concise


2. Keep it accurate


3. Make it complete

Software engineers work under very stressful deadlines. When they need information they need it now. They want to go in, find the answer they seek, and return to whatever they were doing before. Preferably as quickly as possible so they can move on to the next feature they need to code. Therefore, it behooves the writers of technical docs, especially those that address software engineers, to follow a few simple rules to make the information available in a manner that helps the software engineer get on with the job at hand.

Keep the information concise. I do this by layering the information as much as possible. Will the tool tip answer their question? If not, does the cheat sheet provide enough of a clue to jog the engineer's memory so they can continue? Does the link in the cheat sheet take them directly to a page that will answer their question completely. Or better yet, use command-links to take them to the window, view, or wizard that solves their problem?

Keep the information accurate. Nothing worse than having inaccurate documentation, forcing the reader to dig for the info they seek, or worse yet, weigh two or more different pieces of information to determine which one is correct. Verify component names, use the correct terminology, provide copious links to other parts of the manual to answer other questions that may arise during their search.

Make it complete by answering the most common use cases up front. Once those are answered, look at any special cases that can arise and answer those as well.

Solving a user's problem in documentation should be like peeling an onion. Every layer they peel off should reveal more information that helps answer their question. The sooner they get their answer, the sooner they can go back to what they are supposed to be doing, and the happier they will be with your product.

And we all want our customers to be happy, right?