Re: GDP web site

[Dan Mueth <d-mueth uchicago edu>]

On Fri, 5 May 2000, Thomas Canty wrote:

> I visited the GDP web site in order to found out how to write documentation for
> a couple of programs, and i thought the structure of the web site quite
> confusing.... For people starting out writing documentation, it's not clear enough what
> they need to read in order to know enough to starting documenting. 
> 
> It seems to be designed for people currently documenting, not those starting
> out on documentation. There is too much information on the one page to quickly
> find the information a newbie would be looking for.
> 
> I think there should be a separate getting started section that details the
> basics of documenting for GNOME. ( On a separate page) The problem isn't with the
> information on the web site, but rather the way in it's presented that's
> confusing..
> 
> Feel free to disagree with me :) - I am probably the exception rather than the
> rule.
> 
> And maybe this will be fixed anyway when the Gnome web site is redesigned...

The layout will probably change rather substantially when the new site is
made.  This is a good time to discuss what the problems are with the
current site and what we should change when we make the new site. I
imagine the new site will not try to squeeze everything into one page, but
will have a main page linking to a handful of other pages.  It sounds like
we need a QuickStart page or a Newbies page.

I think the information you are looking for is in The GNOME Handbook of
Writing Software Documentation.  Take a look at this document and tell us
what you think. 

We have done a fair amount of work trying to make it easy for people to
learn how to write documentation (GDP web page, Handbook, dcm's new
gnome-doc-tools package, DocTable, active #docs group, document
templates, ...).  Any suggestions on other things we can do to make
documenting easier or on how we can improve these existing tools would be
welcome.

Dan