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.

Validating TOC href attributes

The XML editors available for Eclipse to a great job of helping me form valid Table of Content (TOC) XML files. What they don't do is help me verify that the href entries in the data are correct. To do that I need to basically run/debug a test instance and review the error log to see if my help is broken. Or worse yet, manually test each link.

Now, normally I use Abode Dreamweaver to write, format, and review my manuals, and it has a wonderful verify site links feature that can quickly locate and help me correct broken links in the HTML files. What DW doesn't do is verify links in my XML files. So the TOC XML files live in this limbo area where they are valid in format but may have broken links in them that can only be tested via a compile or manual test.

I've looked around and not found any plugin tool that fills this void between creating and compiling my docs to verify that the href links in my TOC files are valid before I do a run/debug action. Ideally, the tool would simply verify that the href link I create in my TOC file is valid within the plugin project I'm working on, either automatically or via a verify/validate command. Its easy to misspell something in a long path and not know its correct until you physically try the link.

Does anyone know of a tool like this to help doc writers overcome this issue? If not, maybe this is something to look at for a future release to aid the documentation people on the project.

Indexing the obvious

Spent a bit today creating an initial keyword index file for the C/C++ docs. Nothing special, simply a reordering of the reference and task XML file contents so that a user can type in a few high level terms like "view" and "preferences" and see a complete list concerning C/C++.

Noticed some changes in how indexes are interpreted and displayed, both good and bad. The good includes much better resolving of the entry titles so you can leave the title attribute out and if the path shows up in the TOC it uses the name shown there. The bad is that it uses the 'title' attribute instead of the 'label' attribute used by the TOC file. This means any line copied from one file to the other has to have a single attribute changed or removed just to make it work. Do we really need two attribute names for essentially the same action, naming an href page?

For example, in the TOC file an entry shows as (minus the topic attribute):

label="Selecting Views and Editors" href="reference/cdt_u_views.htm"

But in the index file is has to read:

title="Selecting Views and Editors" href="reference/cdt_u_views.htm"

or, the new solution:

href="reference/cdt_u_views.htm"

Either way, you can't just copy and paste. You have to do some editing to replace or remove the extraneous attribute. Hint, maybe in a future release we could make both work for a bit and then slowly deprecate one of them (sorry 'title' we don't need you anymore).

Its also still unclear to me how one controls what is shown when the Index tab is clicked in the Help window. Pre-3.3 if the keyword entry included several 'title' entries, then the keyword appeared with a tree control, hiding the sub-entries under the common name. In 3.3 the sub-entries are always shown and there is no tree control on the keyword. This reduces the number of main entries that can be shown in the index list and forces one to click previous and next buttons to cycle through them a page at a time, no simple scrolling allowed.

Now I know a lot of people are familiar with horizontal scrolling but, I'm sorry, that's simply a UI abomination to me unless its a large image. Lists of items should not force me to scroll in the horizontal direction. Up and down is fine, but horizontal? Was the list getting too large to hold in memory? I've no idea but the click, click, click instead of taking advantage of the mouse's scroll wheel seems like a step backward.

Anyway, even with the above issues it was easy and fast to create the index file and link it into the Index view of the Help window. Hopefully more people will add their own links to the file so that the C/C++ docs will have a kick-butt useful index.

Simple Cheat Sheet Editor Rocks!

So, as one of the first things I decided to contribute to the CDT project were updated tutorials, preferably ones that used cheat sheets and integrated a little better with Eclipse. Imagine my surprise when I discovered the Simple Cheat Sheet Editor. It took less than an hour to convert the original basic and import tutorials to cheat sheet format. And the inclusion of the new Command Composer made linking to wizards and dialogs a breeze. I hope links to the Command Composer are extended into editing of HTML and XML files to make the quick addition of commands to doc pages just as simple.

I'm curious why there is so little use of cheat sheets in Eclipse?

I know in our product documentation my initial idea was to convert every task in the manual into a cheat sheet and call it done. At that time I had little idea of how cheat sheets worked. I simply knew they existed. After awhile though it became obvious that we didn't want to use cheat sheets for every task, but only for those semi-complex or complex tasks that were hard to remember. So we ended up with only a couple of them in the finished product.

And now they're even easier to create, so I urge anyone who thought having a cheat sheet for their product/plug-in would be a good idea to take a second look and give it another try. You might be surprised.