Mon, 02 Apr 2001 08:02:08 +0200
I have been reading the discussions about the "bad" quality of the
documentation. Whilst reading this, there was only one thought that came
into mind: why waiste all this energy on these discussions when one could
discuss a new version of the manual, or change the setup of the
I think that a lot of people forget what it takes to write documentation.
Writing documentation requires totally different skills than writing an
application like Interchange. Above all, Interchange has grown into a
huge application. I would like to call Interchange a CRM application
instead of an e-commerce application.
In essence, I must agree with a lot of comments that the current
documentation doesn't fully cover the load, although there is a lot of
usefull information in it. I therefor call upon everyone to define the
requirements for a new version of documentation, perhaps even an extended
FAQ. One advise from my side: make the requirements as detailed as
possible, otherwise this approach will fail (experienced this for over 10
years of working in this field).
Hopefully this will change the discussion into a constructive one, and
will stop the negative discussion on all the flaws of the documentation.
PS! I really like the work Akopia has done. It's a very good application.
From: "F. James Rohlf" <firstname.lastname@example.org>
To: "Interchange-Users" <email@example.com>
Date: Mon, 2 Apr 2001 01:30:50 -0400
Subject: [ic] RTFM?
> I probably should stay out of this discussion for risk of offending
> again but ...
> If I find many users often make the same mistake in using my software
> then I
> take that as strong evidence that my UI was designed poorly. If users
> asking the same questions then I assume my documentation is not as
> useful as
> it should be -- e.g., the wrong questions are listed in my FAQ file and
> introductory User Guide is not really doing its job. It is
> counter-productive to get upset with the users - they are your
> customers -
> and customers are always right -- even though they can be frustrating.
> If the Interchange list keeps seeing the same questions then someone
> to update and reorganize the FAQ file. It is not reasonable to ask
> to sift through all the IC archives for the past year before they can
> ask a
> question. It is reasonable to ask them to check a well-organized and
> FAQ file first. Even better would be for the documentation to be
> updated on
> a regular basis as questions are asked about particular features where
> documentation is unclear. Why not take advantage of the fact that the
> documentation is on-line so it can easily be undated - at least add
> Probably most people reading this list are devoting a fair amount of
> trying to understand IC - at least enough to get a store up and running
> way they want. The conflict is that most of us also have other
> responsibilities that demand our attention. We don't have the luxury of
> spending a year to become at one with IC. Like others have commented, I
> have printed out all the PDF files and have turned every page and stuck
> post-it notes on many of the page so I can find them again. I suspect
> most readers of this list are pretty smart and could make IC do pretty
> things if just they had the information they needed.
> It is clear that IC is very powerful and well-designed (I am quite
> impressed) but reading its documentation and learning how to use IC is
> frustrating because it is more difficult than it should be. I could
> use an
> "IC for Dummies" book to get me started and then I could go into the
> when I need them.
> Interchange-users mailing list