[ic] RTFM?

[Guy Soudant]

Hi,

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 
documentation.

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.

Kind regards

Guy Soudant

PS! I really like the work Akopia has done. It's a very good application.


-----Original Message-----
From: "F. James Rohlf" <rohlf@life.bio.sunysb.edu>
To: "Interchange-Users" <interchange-users@lists.akopia.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
> others
> 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
> keep
> 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
> my
> 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
> needs
> to update and reorganize the FAQ file. It is not reasonable to ask
> everyone
> 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
> indexed
> 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
> the
> 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
> footnotes?
> 
> Probably most people reading this list are devoting a fair amount of
> effort
> trying to understand IC - at least enough to get a store up and running
> the
> 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
> too
> 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
> that
> most readers of this list are pretty smart and could make IC do pretty
> neat
> 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
> details
> when I need them.
> 
> Jim
> 
> 
> _______________________________________________
> Interchange-users mailing list
> Interchange-users@lists.akopia.com
> http://lists.akopia.com/mailman/listinfo/interchange-users