Welcome to the first issue of the GNOME Documentation Project Status Report. The GNOME Documentation Project Status Report will be a (roughly) biweekly report describing the recent events of the GDP (GNOME Documentation Project) and the status of various documents. I hope that these reports will be useful for GDP members, translators, developers, and potential GDP contributors. If you have any submissions or suggestions for these Status Reports, please send them to <d-mueth@uchicago.edu>.
The goal of the GDP (GNOME Documentation Project) is to provide a complete documentation system for GNOME. The main part of this is writing and maintaining application manuals for all applets and applications in the main GNOME distribution and GNOME Office. The GDP also writes other user documentation such as application hints (a la gnome-hint), pop-up help (coming soon), the GNOME User FAQ, and the GNOME User's Guide. The GDP also writes and maintains developer documentation such as API documents, White Papers, and developer tutorials. These developer documents are generally written by developers who work with the GDP since it requires technical expertise on the particular topic. And lastly, the GDP, along with various GNOME hackers, is responsible for designing the different components of the GNOME help system, such as the tutorial/demo wizard (coming soon), pop-up help (coming soon), and the documentation browsing system.
The GDP is always looking for new volunteers to write documentation or help in other ways. If you are interested in joining or contacting the GDP, visit the GDP web page or chat with us on IRC at #docs on irc.gnome.org.
GNOME needs volunteers to write developer documentation. (See below for details)
The GDP templates have been updated. Grab them here.
The GDP Handbook has been updated to fix all the broken thinks caused by the new www.gnome.org and GDP web pages.
The GNOME help browser will use a metadata system based on the OMF for managing information about documentation, such as title, format, document location, subject, position in Contents List, and versioning information. The core of this system is being developed in collaboration with other documentation projects to guarantee that the end product will be adopted by other help browsers and documentation groups. We are currently looking for a developer who would like to help design and implement this core system.
Eliot Landrum recently made a deb of gnome-doc-tools. (This package contains the GDP's DocBook DTD, stylesheet, and a couple useful scripts.) The RPM and tarball can be found at the GDP Resources web page.
Thanks to Kenny Graunke, the GDP now has a new and improved web page. It is now part of developer.gnome.org. There is now a Projects section on developer.gnome.org, so other GNOME projects should consider moving their web pages here too.
It is very important that GNOME has complete, up-to-date, and high quality developer documentation. This is important to help developers (both individuals and commercial companies) evaluate GNOME as a development environment and to improve the quality and speed of development of GNOME applications.
Eric Baudais is compiling a detailed list describing the status of GNOME's developer documentation. If you have written any developer documents in the past, please send Eric an email indicating whether the document is up-to-date and who the current maintainer is (or that the document needs a new maintainer if that is the case). If you are interested in writing or maintaining developer documents, please contact Eric.
The whirlwind documentation effort prior to the release of GNOME 1.2 produced an amazing amount of documentation which was released. However, a fair number of documentation bugs slipped through. Kevin Breit has made a documentation bug list(Gnumeric XML format) to keep track of them. Let's try to fix these bugs soon. (Kudos to John Fleck and Gregory McLean who quickly fixed all of the gnome-utils docs shortly after 1.2 was released.)
Thanks to Telsa Gwynne, we now have an excellent new GNOME User FAQ. Now when newbies ask you lots of questions, you can look up the answers in here and look like you know everthing about GNOME. Help Telsa make this FAQ even better by sending her your suggestions.
Telsa wanted to pass along the following notes:
I don't guarantee it won't hose your system.
I haven't personally verified the build order.
I would dearly love updates specific to non-Linux systems.
gnome-docu/gnome-faq/ has TODO and README files (not in FAQ and not in tarball). In particular, the "check it passes db2html before committing the DocBook". I should add "don't commit the bloody HTML results either", too, I think!
On July 16, O'Reilly hosted an Open Documentation Summit. Most of the open documentation projects were represented there, along with many specialists in various aspects of documentation. The attendees identified a number of possible solutions to address weak points in current documentation efforts, places where the various groups can collaborate to avoid duplication of efforts, several ways the current open/free documentation licenses can be improved, and target formats which will be used by all projects. They also decided upon a metadata standard which will be shared by all projects to catalog documentation. For more information, read Frank Willison's report or Dan Mueth's report.
We are currently looking for a developer who can start writing tools to work with this metadata. If you are interested in working on the new metadata system for cataloging and searching documents (both locally and on the internet), contact Dan Mueth.
In future versions of GNOME the help documentation will be displayed in Nautilus which will replace the current GNOME Help Browser. We plan on implementing many new features, such as index browsing, a contents list, searching, a glossary, and cross-referencing. Ali Abdin has been working hard to make these plans a reality. However, a lot of work remains. In particular, we need somebody to work on document searching. If you would like to help work on this new system, send an email to the GDP mailing list.
Kenny Graunke has packaged the The GNOME Handbook of Writing Software Documentation (also known as the GDP Handbook) in convenient tarball and RPM formats. (Sorry, no debs yet.) Get it here. It installs in the right path for the GNOME Help Browser to find it using ghelp:gdp-handbook.
Aaron Weber has begun a section in the GDP Handbook which discusses writing style. Everybody should have a look at it for some good suggestions on how you can improve your writing. If you have any suggestions for improvements or changes in the GDP's writing style, send an email to the GDP mailing list for discussion.
We are looking for volunteers for the following tasks:
We need people to work on the following:
Fix doc bugs remaining from GNOME 1.2 release. (documentation bug list in Gnumeric XML format)
Create test suite of docs for testing Nautilus.
Test Nautilus based help system. Please send all bug reports to Eazel's Bugzilla server. (Note: This involves building Nautilus out of CVS.) (Contact: Ali Abdin)
Create subject tree for a Contents list which includes all types of documentation on a system.
We need developers to work on the following:
Add searching to Nautilus-based help system.
Write API docs.
Write/maintain developer tutorials and white papers.
Develop tools to manage OMF metadata which will be used to catalog documents.
We need document authors to work on the following documents:
We are looking for volunteers to maintain the following documents:
GNOME & CORBA
GNOME Developer FAQ
This is a list of documents which have recently been updated or finished. It is meant primarily to help translators, but may also be of use to package maintainers and users.
GNOME User's Guide
GNOME User FAQ
gedit
gabber
This is a list of documents which have been finished for a while, but are still good candidates for translation. They are sorted by package.
gnome-utils (essentially all apps: gcalc, gcharmap, gsearchtool, gdict, gfloppy, gstripchart, gtt, gless, guname, gw, gshutdown, idetool, gfontsel, gdiskfree)
gnome-core (Panel, all applets in gnome-core, gnome-terminal)
gnome-applets (almost all of them)
gnome-games (Iagno, Aisleriot)
bug-buddy
gtop
Glade FAQ and Glade Quickstart Guide
If you have any questions or suggestions about this GNOME Documentation Project Status Report, please send them to <d-mueth@uchicago.edu>. If you are interested in joining the GDP, check out the GDP web page, especially the section on Joining.