Re: summarizing docs-on-the-web discussion

[Malcolm Tredinnick <malcolm commsecure com au>]

I realise John was just trying to give a general picture here, but I
though I'd fill out this list a bit so that we can kill two birds with
one environmentally friendly stone.

On Wed, Oct 23, 2002 at 07:53:39PM -0600, John Fleck wrote:
[...]
> In my naive thinking, we'd have a directory structure something like
> 
> all user docs
> 	gnome applets
> 	gnome-utils
> 	gnome-user-docs (includes users guide and other bits

Does gnome-user-docs include the FAQ (you know, the one that hasn't been
written yet)? If not, that has to be somewhere. At least as a list of
pointers to the right documents to read.

> 	gnome-games
> 	gedit
> 	gnumeric
> 	etc.

	System administrator's guide (start with the one Sun is writing
	and generalise it over time)

> developer docs
> 	api docs
> 		gtk api
> 		gnome-xml api
> 		libxslt api
> 		etc.
> 	development tutorials

	developer articles  _____
	                         \
	developer white papers ---+- (both different from tutorials)
	developer FAQ

	HIG
	Accessibility guide (see below before raising your hand with
	objections.)

There are probably also some other ones in Telsa's ueber-bug that she
made a while ago.

> My thinking is clearly based on an organizational structure that mirrors
> the way we organize stuff now in CVS, but I'm clearly not wedded to
> this. Ideas welcome, as well as advice on what you need to know to
> proceed with this.

It's also going to be pretty important that the "overview" point
includes things like the accesibility and human interface guides in a
seamless fashion. I would like to see a "start here for documentation:
first floor, user docs; second floor, developer docs; free parking on
the rooftop level."

People looking at the website for documentation are not going to care
one wit whether the usability or the a11y or the docs project manages a
particular document. They are just going to be looking for documentation
and having to wander about all over the place trying to find the doc
under the appropriate group's cover page is painful (that is a problem
with the current d.g.o site).

It's nice to see all this starting to come together, at least on paper.

Malcolm

-- 
I intend to live forever - so far so good.