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.
Thursday, June 21, 2007
Friday, June 08, 2007
My 3 rules of technical writing
When writing technical document, especially for busy software engineers, the three rules I follow include:
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?
- Keep it concise
- Keep it accurate
- 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?
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.
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):
But in the index file is has to read:
or, the new solution:
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.
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.
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.
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.
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.
Subscribe to:
Posts (Atom)