Re: G2 Lessons Learned

[Eric Baudais <baudais kkpsi org>]

I think the DocTable will need some modification if we are going to keep
it.  The DocTable has these pies which should show the status of the
document.  I find that the pies needed a long explanation to tell
exactly at what point the documentation currently it at in its
lifecycle.  The DocTable also has a limited space for people working on
the document.  This led to multiple people being in the same fields.  I
think each field should show the person's name, their contact
information and how they relate to the document (author, contributor,
editor, app maintainer, etc.).  I also find the DocTable doesn't tell
much about the document itself.  I would like the DocTable to tell more
about the document.  Basically the information that is put in the OMF
file would be a starting point.

There are also some strong points about the DocTable.  I liked how the
DocTable showed exactly where the document is located.  This is a real
benefit when you need to look it up quicky.  I liked how the DocTable
tried to get the app maintainers involved by including their contact
information.  I liked how the DocTable showed a brief summary about each
document on its listing.  I also like how the DocTable displayed its
information about the documents using HTML and you could edit entries in
the DocTable using HTML forms.

Should we keep the DocTable and try to modify it to fit our needs or
should we look into another document management system?  To answer this
question I think we need to look into the purpose of the DocTable.  I
think the purpose of the DocTable is to provide a consistent interface
where information about each document can be easily obtained.  The
information should show how to get the source as well as different
formats of the document.  It should tell who is working on the document
and their relation to the document.  It should display information about
the document's versions and track the document's progress.  I don't
think the DocTable accomplishes theses goals in its present state. 
Unless someone wants to play with the PHP code and change it I would
suggest we look at another document management system.

There are two open source documentation management systems available. 
Bourges by Mandrake and Lampadas by David Merill of LDP fame. I've
looked at both systems and will give what I think are the pros and cons
of each system.  

First Bourges is more of a content management system in that it manages
the content inside the document as much as it manages each individual
document.  Bourges has a XML based configuration and each document needs
their own XML file.  This will require a lot of setup and management on
our part to start and take care of the system.  Bourges is based on
individual DTDs.  Each DTD will have a way to make PDF and HTML. 
DocBook is the only supported DTD currently.  The documents each have
different states they go through and are divided up into basic sectional
components to track the document's progress.  Bourges tracks document
revisions and translation status of the document.  Bourges needs a
specific top level document structure.  The rest of the manual is
compiled using entities relating to each part of the manual.  This I do
not think is a good thing for the GDP as we already have a predefined
way to compose manuals.  Bourges makes reports about each document's
status in HTML.  You can also email the reports to the authors of the
document.  Bourges integrates with CVS, but there is not much
documentation about it.  Supposedly you can pick and choose what to put
in CVS and what not to.  Ultimately Bourges seems like a nice full
featured document management system, but may be a bit of an overkill
with its detailed status management system.  I would also like to see a
search tool so prospective documenters can search the database looking
for apps they wish to document.  There are also some interesting
questions about how Bourges will be able to integrate into our present
documentation.  I believe some of the current documentation will have to
be modified to work with Bourges.

Lampadas is a HTML based documentation management system using perl
scripts.  There is a listing of all the topics in the left navigation
bar.  The DocTable itself has a complete listing of each document or you
can click on a topic and view the documents in topical list.  Each
document has an extensive metadata entry.  The source as well as the URL
of the document is listed.  Any revisions are displayed and can be added
from the HTML form.  All the document's contributors are listed and you
can rate and add comments about the document.  The drawback of Lampadas
is the lack of a system showing the document's status in development. 
Lampadas does show the state of the completed documents.  Also only an
HTML version of the document is shown in the listing of documents and
nothing else.  Lampadas does not show the current docs very well in its
default setting.  Lampadas is also under development and will not be
ready for production use for another one to two months.

I really like the potential Lampadas shows.  It does need to report the
state of the document under development better though.  Also showing the
status and current author of all the docs in the DocTable is needed.  If
Dave corrects these things I believe Lampadas will fit our needs.

Eric Baudais

On Mon, 2002-07-01 at 11:21, Jon Allen wrote:
> I didn't start using GNOME until about 1.4 so I have no idea how effective
> the Doctable was back then.  Perhaps the current Doctable infrastructure is
> sufficient but needs to be used?  I'm wondering if we need to go out and
> re-invent the wheel if we have a system already in place.  If the Doctable
> in its
> current form is actually a useful tool when used consistently, I vote to
> stick with
> it because:
> 
> 1. We don't have to install/customize/learn a new doc tracking system.  [1]
> 2. We don't have to change our methods dramatically to support the new
> tool.
> 
> Also, adding a 'newbie tasks' section to the doctable might help get new
> documenters going in the right direction.
> 
> Jon
> 
> [1] This will avoid the ever-present GNOME sysadmin issue, and besides,
> I won't have to update the webpages till the wee hours of the morning to
> support
> a new tool ;)
> 
> On 01 Jul 2002, John Fleck wrote:
> >
> > Doctable
> > 
> >   We need to solve this problem. We floundered for a long time and
> >   lost energy and momentum because there were people wanting to do
> >   something but no clear way to figure out what needed to be done
> >   short of some sort of IRC ESP thing. In the past, the period of
> >   greatest momentum for the GDP was in the development of GNOME 1.2,
> >   when there was a ton of documentation to be written and you could
> >   just log onto the Doctable and easily find a task. The temporary
> >   Doctable helped noticeably, but really sucks.[2]
> > 
> 
> -- 
> Jon Allen :: jon jonallen org :: http://jonallen.org
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
>