library.gnome.org (libgo) is planned as a location to display documentation of unstable, stable and past releases of GNOME platform for users, administrators and developers in a rich user experience. libgo is a part of a new www.gnome.org revamp effort but it's implementation will not be integrated into whatever will drive wgo.

1. Introduction

It is aimed to be a place where users can browse and interact with up-to-date online documentation by writing and sharing annotations and a place where they can report bugs and learn how they can get involved in process of writing and translating documentation.

As it will be a place to present documentation for developers, like API references and other maintained documents, it will take away some of the content from developer.gnome.org web site. (look here, and here for more info on dgo future)

libgo is developed by Goran Rakić as his Google Summer of Code 2006 project and here you can see original Project proposal. Some parts of these pages goes way beyond what is planned as SoC2006 requirements, and are just a plans for further development. I will mark that parts in italics.

Server config: See /ServerDetails for the current configuration (on gnome.org server). This hopefully has enough hints on how to set it up locally.

2. Concept of channels

As libgo will contain both users/admins and developers docs, which are having different audience, I came to a concept of distribution channels. libgo homepage will reflect this using two distinguish colors for interface of different channels. Initially, I planned to have two channels - for users and for developers, but after some reading on live.gnome.org, I am thinking of latter adding one more - for administrators.

2.1. For users:

• Desktop user guide
• Desktop accessibility guide
• User manuals of programs that are part of GNOME

2.2. For developers:

• API documentation

• Maintained developer guides

• Documentation on standards we follow (freedesktop.org, RFCs, etc.)

• Other material for third-party, non-core-hacker ISV people located elsewhere on the net, not suitable for live.gnome.org

• Selected documents from live.gnome.org wiki tutorials or gnome.org CMS)

2.3. For system administrators: (latter)

• System administrators guide

• Manuals on sysadmin-related programs (like Sabayon)

• Case studies of deployments (something like Frederico has done)

Content will be periodically autogenerated with a tool that is developed in Python. Implementation is extremely flexible and there are many level of abstractions so it is easy to support all sorts of documents stored on different places etc. There are many more details on implementation on this page.

3. Big picture

Speaking about documentation flowchart described in Paolo Borelli's comment on Live Documentation Editing, libgo takes it place as static content provider and an easy way for users to give Feedback on documentation either by writing annotations or using libgo's frontend to bugzilla to fill a bug report. Latter, Live editing tool like sarma or something else can be integrated into libgo. I will stick to annotations only for now.

4. Schedule

4.1. Planning

(completion by the end of June - done!)

When executed, libgo tool update content source located in cache from CVS/SVN server, generate XHTML files and write them down to output dir. At the end it generate index files for browsing and prepare annotations storage.

Documentation fetching and building is done with a concept of locators (that find document items to be built), decorators (that can do a tweaking of how specific document item is built) and document objects (that represents document item and have all the informations how to convert themselves into XHTML files for output). You can look at this page for more informations on implementation design, support for localization and how locator and build process for user's documentation is implemented.

Support for annotations is implemented using JavaScript, but libgo interface is usable even without JavaScript enabled (when annotations are not available). I don't know if I will use server-side generated JavaScript files (imported with <script src="..."> tag) or I will do annotations loading using XmlHttpRequest but either will work. Look here for more info on annotations.

When localized pages are generated, standard Apache MultiView method is used, with English as a fallback language, but there is a way to override your browser settings with a cookie set from JavaScript (and this require JavaScript to be enabled).

4.2. Mockup building

(completion by the end of June - done!)

I designed interface based on "ReadUp: A Widget for Reading" paper by William C. Janssen. Page has two columns, so text rows do not get too long (which is then very hard to trace with eyes), but CSS will hide second column for printing. In right column, there are 2 tabs: Sections and Annotations (Based on feedback I've got from Thomas Wood, I am removing "Pages" tab and rearranging Prev/Up/Next buttons as horizontal.) (some navigation buttons are desaturated if navigation action isn't available), followed by the buttons for selecting different format (PDF, Single HTML page, Multiple HTML pages) and printing, and search button at the end. Keyboard shortcuts will be provided for these actions.

Larger: lib1, lib2, lib3, lib5, lib7

Please note that browse by keyword will not be available for first stable release, and I am planing to integrate this feature with goals of Project Mallard on providing tasks based documentation. Also, Annotations are not longer saved in cookies but on server side as storing on server side make annotations sharing and editing documents using annotations possible. More info on annotations.

For UI design, I was using Tango color palette, and few Tango icons.

I am already planing to provide RSS feeds for recently updated documentations for every channel and for every suported language (language feeds have list of recently updated documents, translated to a selected language) so user can choose what feed to subscribe.

4.3. Developing

(completion by the end of August - in progress)

I planned to this in iterative manner, with small pieces added in each step. But now when I am coding, I want to have one set of features finished before releasing, so if somebody want to play with it can see something of bells and whistlers. Except to see code in next week.

Please, read notes about how I am doing implementation, and what I am calling a concept of locators, decorators and document objects on this page.

4.4. Wrap-up

(completion by the end of August)

Final tweaks and setup on a public test platform.

5. Thoughts/Ideas

These points come from GnomeWeb/GuadecNotes:

• Business/ISV
• php.net style documentation (official docs with moderated comments attached)
• GPLv3 draft style community comments (comment on parts of the text and maintainers can get the feedback and include it, see the most unclear parts, etc. Normal view shows canonical text but comment viewing can be turned on at will.)
• Business support
• Developers (lack of direction)
• Business (embedded)
• Publish all "desktop" documentation for several versions of apps (e.g. for gedit 2.x → 2.y (you can check out apps without installing. we can support users of other verisons of software by seeing their version of docs)
• Wiki documentation (with administrators filtering content)
• Pygtk content should be moved into developer area
• Tutorials

6. Comments

(((Many of these comments were originally published at GnomeWeb/DeveloperGnomeOrg - moving them here)))

• We need to agree on the permissions of anonymous and registered users not directly involved in projects or documentation. Can everybody edit pages? Comment on page? Send feedback to the developers? -- QuimGil

  • I think the ability to for all users to edit documentation is critical. If I, as an API consumer, take the time to figure out an undocumented piece of API, giving me the chance to document it then and there with a minimum amount of effort means I'll probably do it. Right now, I have to check out a copy of the source, find the code, write the documentation in some arcane (and mostly undocumented!) format, create a patch, open a bug, and attach it -- that's way too much work, since this situation occurs in the middle of working on something else. There are plenty of solutions to keeping quality high -- peer review, a moderation queue, etc. The point is to lower the barrier to creating API docs as far as possible for those who aren't involved already but might help out when they run into doc holes. Lots more thinking on the subject of API docs at http://zero.navi.cx/wiki/index.php/Documentation_System for those interested. -- DavidTrowbridge

    • Yes, and the library.gnome.org project is trying to achieve this. However, this is not the only aim of library.gnome.org (up-to-date online documentation is arguably a more important aim), and shouldn't block the other aims. MurrayCumming

    • If we confirm that the future of dgo is simply library.g.o, then we need to check that GoranRakic gets this feedback for the platform he is developing. See GnomeWeb/Library, also Suggestions for library.gnome.org features and LiveDocumentationEditing -- QuimGil

    • David, incase you are reffering to gtk-doc by "documentation in some arcane (and mostly undocumented!) format" then please note that gtk-doc in fact has a full user-manual. Please file a bug report if you think it lacks details. Maybe you can also refine your statement given above. StefanKost

• I would far rather single a single, integrated CMS serving as much content as possible. If we're going to have a CMS serving user-oriented pages, then why have a separate wiki serving developer-oriented pages. Currently, lgo is plagued by poor navigation, excessive editorial comments, and silly wiki words. Our current wiki offering works well for planning pages such as this one, but not so well for a polished and professional web presence. Rather than having a wholly separate wiki, surely a good CMS would allow us to have wiki-esque "scratch pages" that are properly integrated into the site's navigation. -- Shaun McCance