Re: Documentation and Reviews.

[Mike Sangrey <mike sojurn lns pa us>]

miguel@gnu.org said:

[some text deleted]

> Federico, Ettore and me have been working very hard on documenting
> gnome-libs, but a lot of the code was not written by us and to make
> things worse we are not native speakers, so the documentations sounds
> like this:
>          "My name is john"
>     "What is your name?"
>     "I am 15 years old.  How old are you?"
>     "Good morning teacher".

> Please, help us out here:

>     1. We need to finish the entire documentation of the GNOME
>        libraries, this means: adding in-source API documentation to
>        all public entry points and filling in the blanks of the
>        appropiate "template" file.

>     2. We need people to provide example code for all the API calls.
>        Having the pure API call sometimes is not enough.  Please, do
>        help us by writing short examples that we can include.

>     3. Review the existing documentation and make sure it looks good,
>        it covers the topics it should cover, contains good english,
>        contains good examples and is clear to follow.

>     4. Help us distributing the help: making sure the proper files are
>        installed in the proper locations on the system, that the
>        Makefiles are sane and so on.

> Best wishes, Miguel. 

I would be glad to help.  Over the last week I've been subscribing
to GNOME email lists, setting up CVS, perusing the source, setting up
DocBook, etc.  I'd like to help with the documentation!

Here are the questions I have  (and some introduction to who I am):
    1.  How have you divided up the work?  How many people are
	involved with documentation--just the three of you?  Do you
	have a plan and, if so, where are you at?  Ultimately, where
	I'm driving to with these questions is how and where can I
	get involved?

    2.  I have 10 years experience in C, 8 years experience with
	GNU tools (porting, hacking, general fun sort of stuff), and 6
	years experience with Linux.  So, I can move through the code
	fairly easily; however, I've never done X programming of any kind.
	I won't be efficient at producing the examples; however, I'll
	know whether they're any good.  Can I fit in here?

    3.  I can review the existing documentation.  I would be glad
	to improve the language that reads like, "See Gnome.  See
	Gnome run.  Run Gnome run."  :-) -- perhaps I shouldn't have
	poked fun during this hectic time; let me just say that I
	understand and I'm with you on this.  Do we have a review-release
	cycle established in CVS, or possibly ideas to that end?  If so,
	could we use that?  Do you have ideas about how I may proceed
	with reviewing the documentation?

    4.	I might be able to help with Help.  However, I don't
	know--yet!--how the help system is integrated into the Makefile
	architecture.  Makefiles are no big deal for me.  (e.g. even GCC's
	makefiles do not cause me to run screaming from the room.)
	Can I fit in here?  Can I get some guidance concerning the
	help documentation structure?

Lastly, and most important, I hope this email isn't coming across as
"tooting" my own ego horn.  My intention is to quickly introduce
myself in a way that hopefully conveys what I can do; and, I want to
give you enough information so you can initially guide me.  The intent
is for everyone to benefit.  Viva la Gnome.

Thanks.

P.S.  One other thing I might mention.  I was recently layed off from
AMP, Inc.  The bad news is that I am working on two major projects: 
one, find work; and two, sell the old house and build a new house.
Even still, the good news is that I want to be involved with Gnome;
and I think your point regarding the importance of documentation is
right on, so I'll make time (just don't tell my wife...please:-)




-- 
Mike Sangrey
mike@sojurn.lns.pa.us