[Docs] Re: [MAILER-DAEMON@accessgroupinc.com: Returned mail: User unknown]

Mike Heins docs@lists.akopia.com
Fri, 20 Jul 2001 14:53:58 -0400


Quoting Bob Ramstad (rramstad@alum.mit.edu):
> When the beta docs are available, let me know directly or by posting
> to the interchange-users list (I'm subscribed now) and I'll be happy
> to take a look and offer any comments.
> 
> I recognize that my comment might have been taken in a negative light,
> and I meant for the criticism to be constructive i.e. with a
> complicated and powerful system like Interchange, the documentation is
> critical.
> 

We did put a reference to the new docs in the release note:

	http://ic.redhat.com/cgi-bin/ic/dev-4.8/index

> The tutorial was excellent, and in general, I think that people need
> lots of examples.  I suspect most people would prefer taking a stock
> system and tweaking it slightly as opposed to starting from scratch.
> 
> The thing I found most confusing / most difficult / most worrisome is
> that in 4.6.x there are lots of defaults -- for things like error
> pages, basket pages -- which are required, but seemingly not all that
> well documented i.e. it seems to me that one major issue is that there
> doesn't seem to be documentation anywhere about a canonical minimal
> set of pages in the default locations to make a functioning catalog.
> 
> I have a nightmare about missing one special page and having all of
> our catalogs crippled and not know about it until it's too late.

Hmm. As far as I know, there is nothing about a special page that would
"cripple" a catalog. All are intended only to deal with error conditions
or provide default actions for the most common things -- ordering,
searching, and product viewing. For the most part, what you see is what
you get.

There is a decreasing reliance on special pages as time goes on -- in
fact, except for the very special case of a 404 error, you would mostly
go without seeing one. Except in that case, all pages can be specified
directly with an mv_nextpage=pagename reference. The special pages are
all by way of default for a common action.

In any case, we would be very happy to see detailed analysis of the new
docs, in particular if there are specific suggestions for improvement.
General comments, though certainly read, are not so useful in the short
term. We have lots of those already, and their main value is to get a
general idea of what readers are thinking. 8-)

Thanks for taking the time to comment --  future comments about the
docs are probably better sent to docs@lists.akopia.com, where I have
copied my response.

-- 
Red Hat, Inc., 3005 Nichols Rd., Hamilton, OH  45013
phone +1.513.523.7621      <mheins@redhat.com>

I don't want to get to the end of my life and find I have just
lived the length of it. I want to have lived the width of it as
well. -- Diane Ackerman