Bugs about docs we need, which need hackers and sysadmins to write
- From: hobbit aloss ukuu org uk
- To: gnome-hackers gnome org, GNOME Desktop List <desktop-devel-list gnome org>
- Subject: Bugs about docs we need, which need hackers and sysadmins to write
- Date: Thu, 29 Aug 2002 13:39:49 +0100
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
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
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
Summary: d.g.o needs more detail about CVS use
...which I have assigned to me cos it's pretty much done.
Summary: We need a GNOME 2 FAQ
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
'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
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
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
"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
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
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.
] [Thread Prev