GNOME Developer Documentation

[Dan Mueth <dan eazel com>]

One of the topics which kept coming up at GUADEC II was the need for much
better developer documentation for GNOME 2.0. It was generally agreed that
we should have a 100% documented API.  We came up with a few ideas (listed
below) on how we can make this easier to achieve.  We also need to have
updated and complete white papers and tutorials.  These materials should
all be available both on http://developer.gnome.org (d.g.o.) as well as
downloadable as part of the GNOME packages.

I put together a brief outline of what I think we need to do to make this
all happen.  Feel free to give feedback on this outline or to volunteer to
do any task which has an assignment of "(???)".  If you would like to
contribute in any way please email me.

If you are a module/project maintainer, please evaluate the status of the
material currently on developer.gnome.org for your module/project and send
me an email indicating whether the information is up-to-date or needs to
be rewritten.

Dan

--------

                     GNOME 2.0 Developer Docs Plan v0.1
                     ----------------------------------

API Docs
--------
Aim to have mostly completed by July 31, and 100% complete by Aug 15.

Gtk-doc:
	1) create m4 macros so that setting up gtk-doc in a module is 
	   much easier (Maciej?, ???)
	2) Merge and improve existing documentation into a single DocBook
	   doc and put on d.g.o. and in gtk-doc package and RPM. (???)
	3) Create example packages illustrating how to set up a module
	   with gtk-doc (???) 

Web:
	1) Set up a web page which shows the status of API documentation for
	   each module. (???)
	2) Update scripts to build docs and place them on d.g.o. as 
	   necessary (???)

Writing:
	* Package maintainers are responsible for making sure the module
	  they maintain is documented on time.
	* It is strongly encouraged that package maintainers do not accept
	  patches which do not include any necessary documentation updates.
	* Package maintainers whose API docs are not completed on schedule
	  will be publicly shamed.


White Papers, Tutorials, etc.
-----------------------------
Templates:
	1) Create templates for tutorials, white papers, etc (Dan/GDP,???)

Modules:
	* Docs should be placed in the module they describe if
	  appropriate, and be shipped in the <lib>-devel package.
	* For devel docs which do not clearly belong in a particular module,
	  put them in gnome-devel-docs. (Please email dan eazel com before
	  adding a new document to this module.)

Licensing:
	* Please license under FDL (GNU Free Documentation Library) if 
	  possible

Format:
	* DocBook/SGML (of course)

Web: 
	1) These documents should be automagically built from CVS and placed
	   on d.g.o. (???)


http://developer.gnome.org (d.g.o.)
-----------------------------------
1) Review.  Remove obsolete contents.  Update. (Kenny?, ???)


GNOME Platform Overview 
----------------------- 
Right now, d.g.o. has an overview of the GNOME platform presented under
the many subsections of "Architecture".  Each item is described by a few
short paragraphs and any relevant links are listed at the bottom.  This is
a really valuable resource for people getting started. (Except that it is
very out-of-date.)  This should be available in a downloadable and
printable format.

The easiest way to do this is probably to just reproduce this with updated
content in a DocBook/SGML document.  This document could be placed in
gnome-devel-docs for distribution.  For d.g.o., we would replace the whole
"architecture" section of the web page with a link to the HTML version of
this page.  The biggest downside is that we lose the very nice d.g.o. look
and feel.  If we want to keep the d.g.o. feel, we could probably come up
with a script which merges the HTML output generated from the DocBook docs
into the templates used by d.g.o.

Another option would be that each page is an entity which would allow us
to generate the d.g.o. pages by using an appropriate stylesheet.

(Does anybody feel particularly strongly about how we handle this or
if we even just have a single HTML doc replacing the Architecture part
of the tree?)


Other
-----
We should make all documents available in printable form (PS or PDF). This may
be from the web page and/or the packages.  (Probably just the web pages.)

Update GDP web pages and Handbook to have more info on devel docs (Dan).