Bugs about docs we need, which need hackers and sysadmins to write

[hobbit aloss ukuu org uk]

On Thu, 2002-08-29 at 08:12, Jeff Waugh wrote:
> Telsa has just kindly lodged a bunch of relevant bugs on the 
> release team with regards to documentation and such (assigning 
> them all to me in the process - GAR!)... When the FTP and 2.0.2 

Not all. I left one for me. :) I actually -want- to do several 
of them, but since I have been meaning to for about a year
for some of them, I think you shouldn't wait for me...

> stuff is done, I'm going to get stuck into those.

Actually, my plan is not that the release team do them all. 
Some of the bugs are things many of us just can't write. :) 

This email is a call for anyone who wants to take on one of 
those bugs _please_ to do so. I have zillions of notes for 
many of them: I have document structure (which I have found 
to be the hard part) drafted out for many of them; I have a 
collection of things I have seen asked again and again saved 
from mail and IRC, which I can add as attachments or mail to 
people interested; I have notes from people about the evils or
otherwise of -Wall, -ansi, and so on for gcc and the tendency
to presume that bash==Bourne shell (etc) which I am quite
unable to write up fairly (knowing nothing about it), and
so forth. 

I think the right format for almost all of them is DocBook.
It can be turned into HTML or PDFs then. You do not have
to write in DocBook, though. Several of #docs have said
you are welcome to send stuff to gnome-doc-list for marking
up. I am also very happy to do that. I actually like DocBook
and marking it up. I have even been known to mark up code
correctly. 

Without further ado: here's the bugs so far. There is 
much more discussion and suggestion in bugzilla. I have
just appended extra thoughts I had as I recount this lot,
because I can't reach bugzilla at the moment (thank you,
NTL), which means I can't dump useful stuff into attachments
either. 

Summary: d.g.o needs more detail about CVS use
http://bugzilla.gnome.org/show_bug.cgi?id=91863
    ...which I have assigned to me cos it's pretty much done.

Summary: We need a GNOME 2 FAQ
http://bugzilla.gnome.org/show_bug.cgi?id=91865
     This is for the users faq. Should merely be taking structure
     of 1.2 faq. Keep attributions straight: makes updating and
     getting permission much simpler. (I had to do the 1.2 one from
     scratch because of that: let's try to avoid that this time.)
     I have a lot of stuff from the gnomefaq gnu org alias which
     needs perusing to snip out Gnome-2-relevant stuff. 

Summary: Needed: Developer FAQ
http://bugzilla.gnome.org/show_bug.cgi?id=9186
    'nuff said. I have a lot of questions I recognise, but not
     many answers. As with the user one, make sure you know
     who contributed what: it makes updating _so_ much easier!

Summary: need a doc on portability
http://bugzilla.gnome.org/show_bug.cgi?id=91867
    This should ultimately go into gnome-docu/whitepapers/
    I have notes from various people about this but I am
    unqualified to do anything with them.

Summary: Need something akin to Paul Coopers sysadmin guide for Gnome 2
http://bugzilla.gnome.org/show_bug.cgi?id=91868
    This is a huge huge huge FAQ: I see it on gnome-list, on IRC,
    on LUG lists... I particularly want "how we did it here" accounts.
    Distro-specific is fine: just mark it as such. I have begged
    for this repeatedly over the last year. Please someone, if 
    you have lots of users running Gnome and have customised it,
    write it up. Even if it's just "I left everything as the
    default and made this one change". 

Summary: Need a list of what our funky-named packages are
http://bugzilla.gnome.org/show_bug.cgi?id=91870
    "eel? bonobo?" -- sounds like a menagerie :) 
    this is along the lines of the gnome 1.2 users faq "what does
    _that_ do?" section, only update it. Make it intelligible
    for end-users (yes, this is hard with a lot of the libraries)

Summary: Need a profiling howto for gnome
http://bugzilla.gnome.org/show_bug.cgi?id=91871
    can't waste all that lovely "Some questions and tips" -> 
    "Speed suggestions" thread on gnome-list and gnome-hackers
    earlier this month! 

Almost all of these bugs have been marked as blocking this one:
Summary: dotplan needs a "developers start here" page
http://bugzilla.gnome.org/show_bug.cgi?id=91873
    there's a list there of all the things needed. It is not
    meant to contain any of this info in the page. It is meant
    to contain links and to be a jump-off point to relevant 
    documentation. If you  have never heard of some of the things 
    I want to link to in the bugzilla entry, then I think the
    need for this page is proved :) 


Note also that gnome-docu/whitepapers and gnome-docu/tutorials
are _woefully_ untouched. If you own one of those, please check
it's still current. If you have something you think Gnome hackers
need to know, then you might want to see about getting it in
there. The README, NEWS and AUTHORS are all empty, btw. 
Whether this is because it contains 'virtual modules' which
have their own, I don't know.

> Hopefully that will form the start of some (hopefully fairly casual)
> policy documents on things like this.

I dunno about policy docs. I just want to get information down,
so it is no longer a matter of thinking "ah yes, so-and-so was
talking about this last year, where's the archives, I can ask
them about it". We really need stuff just plainly available.

Telsa