Tuesday, May 22, 2007

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.

Sunday, May 20, 2007

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.

Wednesday, May 16, 2007

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.

Monday, May 14, 2007

Bugzilla 3.0 released

Woohoo, a new Bugzilla to play with.

We use Bugzilla internally for our bug tracking and enhancement requests. It was easy to setup, does what we need it to do, and generally behaves itself. No real issues to worry about.

Except it's pages are butt-ugly!

That's why I'm excited about two things in the new release, the first is real template + CSS support. Using some standard CSS I hope to customize the appearance of the various pages on our internal Bugzilla to make the UI look better, and more importantly, organize the material shown on the various pages to make them easier to use, simply by re-organizing the fields appropriately. The current design does the job, but it could be much less error prone than it is. Anyway, its something I've wanted to do for awhile and now looks to be a good time to make the change.

The second feature that really caught my eye was the email submission and updating of bugs. We just had a very successful beta for Carbide.c++ 1.2 but one of the issues we had was the shear number of bug reports submitted in the messages posted in the Google group. My people had to surf through all those messages and:

1) see is an engineer had already responded that yes, that is a bug,
2) determine if the issue reported really is a bug, or
3) respond to the user seeking more info to verify step 2
4) once confirmed, log the new bug to our Bugzilla database
5) repeat for the next message

Basically, it was really manually time intensive during the release period when, as everyone knows, time is already at a premium.

So, the thought was to expose a copy of Bugzilla to the next beta group to make the submission, tracking, and interaction with the users more transparent. However, that would mean a second copy of Bugzilla, one for the beta group, one internal. And yes while I know it would be better to simply expose the internal one, the security policy we live with makes that a non-choice at this time.

Anyway, with this new email bug submission and updating feature in Bugzilla 3.0, I hope we can easily create a simple page or two on the next beta site so beta users can submit and update bugs as they find them, removing the manual portion of the activity on our end. We still need to evaluate how well this process actually works but right now I have high hopes for success.

Sunday, May 13, 2007

Introduction

My name is L. Frank Turovich and I've been writing documentation and training in the software industry for 16+ years. It all started with a article published in Nibble Mac called "The MacCipher Machine" and I haven't stopped yet. Since then I've worked on variety of technologies and platforms.

My main interests are in user interfaces, documentation, and training. Making it easy for the user to understand and use the software without resorting to the docs if possible. A hard goal to accomplish with C++ development tools, but a worthwhile one nethertheless. Being a life long Mac user I'm accustomed to features being where they should be and not shoehorned into a dialog option six clicks down in the interface. Trying to make things obvious and easy to understand for the user is one of my goals.

Currently I work for Nokia's C++ Development Team in Austin, Texas. Most of the team hailed from the Metrowerks/Motorola/Freescale group that produced the CodeWarrior for Symbian OS development tools. Nokia thought it would be a great idea to buy the technologies they needed to support their S60 effort, and so far it seems to be working both for them and us. Currently, I manage the support group for the team. IE, we "support" the entire software development effort via user technical support, product documentation, training, and internal IT support activities.

Almost immediately after coming to Nokia they asked us for a grand plan to improve our tools offering. CodeWarrior was getting a bit long in the tooth, didn't really play well in the PC space due to its Macintosh origins, and was not very flexible when it came to adding new features. After some looking around we decided to adopt Eclipse + CDT as the basis for our new tool effort the end result was eventually released as the Carbide.c++ tools. We must be on the right track as the last two releases have won the team Jolt awards in the Mobile Development Tools category.

Anyway, our team just finished the last 1.0 release of the Carbide.c++ tools, which we call version 1.2, to lots of enthusiastic customers. Many of them helped us complete an excellent beta test cycle and were instrumental in helping us eradicate many many bugs. Thank you. We now have everything in place to begin world domination with future products, so keep an eye on us.