A million dollars question

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
brunos
Posts: 218
Joined: Sun Jul 07, 2002 4:27 pm
Location: Bologna, Italy
Contact:

A million dollars question

Unread post by brunos »

I am dealing with the technical and user documentation for a software company, selling publishing systems worldwide. The software modules described in the documentation are very configurable. Authorized staff can modify all menus, keyboard shortcuts, toolbars, main dialog boxes and similar. Systems Administrators of many our customers do it often. This opens a serious question of the user documentation. Everyone claims the user documentation should be task oriented. I agree with this. Therefore, I write a topic such as:

--------
To insert spaces, on the Edit menu, point to Insert, point to Spaces, and then select the option you want.

Press Shift+Ctrl+Space to insert a non-breaking space.
-----------

But, I know that it assumes that the standard Edit menu was not modified, and that the standard shortcuts are not customized. Otherwise, the topic will be just wrong. And the end users, of course, will complain.

I have said before our customers often do a little bit of user interface customization. Some of them do huge customizations. Neither of them update the original user manuals, though (too complicated). Therefore, the end user manuals are always "fuzzy" up to certain extent, let us say, about 20-40% of topics. That is not good.

Since I can't expect the sysadmins will stop to modify the user interface (this is one of our sales points), and that they will start to update users manuals, I've tried various tricks to relieve this problem, at least for a little bit. For example, I have tried to write less specific topics, such as:

--------
To insert spaces, on the appropriate menu, select the appropriate option.

Press the appropriate key to insert a non-breaking space.
-----------

But this is ridiculous, of course. Such information is useless. That was not the solution.

I've tried to automate the documentation. While there were some ideas about how to do it for CHM or HTML files (such as to read the actual menu options and shortcuts from an external, easily configurable files; by the way, this failed to deliver because it was too complicated and it was not working well), it is quite impossible to do it in printed documentation: not least because *it was printed already*.

I've wrote the disclaimer at the beginning of the manual, such as: "the procedures, described herein may be customized on your system, and therefore, the menu options and the keyboard shortcuts may be inexact", but, this is not of the big help, of course. If I put a note in each topic, it is even worse: too many repetitions.

Any bright & fresh idea on what would be the appropriate approach in writing style or manual structure to get around this?

Regards,
Bruno
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Brunos, looks like you're stuck right in the thick of the heated "skinning" debate. This sort of thing is one of the main reasons that many people are radically opposed to customizable user interfaces. :twisted:

It's really an unsolvable problem because you're shooting at a moving target with a bent gun. I've written a couple of help projects for highly-customizable programs, but these were all for customization by the individual user, so it was reasonable to describe the standard setup and the customization methods and leave it at that.

A project customized by the customer for use in-house by lots of other people is a serious problem. My personal feeling is that if there's no way of predicting the results documentation of this kind is the responsibility of the customer. Basic principle: You change it, you document it. End of story.

In today's market this isn't a good way to get satisfied customers, however. Since you can't predict the changes the customers will make the only solution I can think of is to make it easier for them to enter the details for generating their own documentation, perhaps with interactive XML forms, either local or online, or with an online service that could be entirely or partly automated, depending on how much you can charge for the service.

It would all be a lot of work, of course, and would go beyond the current capabilties of H&M.. :roll:
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
brunos
Posts: 218
Joined: Sun Jul 07, 2002 4:27 pm
Location: Bologna, Italy
Contact:

Unread post by brunos »

so it was reasonable to describe the standard setup and the customization methods and leave it at that.
That's exactly what I am doing too...
Basic principle: You change it, you document it. End of story.
I'll hire you as my attorney, thanks...
In today's market this isn't a good way to get satisfied customers,
:(
the only solution I can think of is to make it easier for them to enter the details for generating their own documentation
That would be the best approach. But (sigh), I lack the "big picture" about what would be the best structure to support it. There must be someone out here who suffered the same problem and survived it. Anyway, let's wait to hear others; perhaps, there's a golden fish somewhere, waiting to hook up.

Regards,
Bruno
John Smith
Posts: 338
Joined: Tue Sep 17, 2002 1:32 am
Location: Australia

Unread post by John Smith »

Bruno,

Now that text variables are here, does that give you the power to change the help files when needed.

For example - Give client a list of menu items that can be customised, They enter next to them their customisations, and either send to you for rebuild (another marketing point - "Customised Help Files") or

if possible run something to update their help files themselves. (Have no idea how this would work, or even if it can)
Ian Feekings
Posts: 4
Joined: Fri Jan 31, 2003 12:27 pm
Location: Queensland Australia

Unread post by Ian Feekings »

Another alternative may be to get the individuals to document their changes and to advise you for updating (provided this has been negotiated in the maintenance price)

They should be made responsible for their changes and to advise those changes.
Post Reply