Re: summarizing docs-on-the-web discussion

[Jeff Waugh <jdub perkypants org>]

<quote who="Malcolm Tredinnick"/>

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

I think that it should. Given that we need to provide a structure for all
user docs in this section anyway, I'd prefer that they were all together.

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

Hmm, yeah.

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

Good call.

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

The plan discussed at various points with regard to the HIG, GDP handbook,
glossary, a11y guidelines, etc. was to combine them into a big GNOME
Developer's Guide series. The a11y/hig part was intended to become the
"Universal Access Guide" (cool name).

At least calling this set of documentation 'Developer Guides' will take a
step in that direction.

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

So, a complete documentation 'sitemap' as well as the docs available from
the user and developer sections? Definitely worthwhile, just not sure where
to put it right now. :-)

Would you prefer that all docs were in one location, and the user/developer
sections linked to it, or that this central map linked to the docs in the
user/developer sections?

(It doesn't make a huge difference to me, or the way the docs will be built
onto the site.)

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

Yes, definitely agree with this! (That's why, currently, the only split is
user/developer, but I can also see the need for a complete map of the docs
available as described above.)

(Adding gnome-web-list back to the Cc line.)

- Jeff

-- 
                          chown -R us:us yourbase