Improving the Docs Project workflow - Innovative Approaches

Innovative Approaches
This section covers new approaches as we collectively discover and/or devise them. The tools listed below are tools that are difficult to categorize. The sections following this section address the tools available for GNOME, KDE and Java environments, respectively.

Wiki into DocBook
The  MoinMoin Wiki converter  aims to "improve and facilitate the use of the Doc Moin-wiki". In other words, by using an agreed subset of the MoinMoin wiki markup language, writers and editors can do distributive online editing, which is then easily converted into valid Doc Moin 1.6 release.

Sarma
One new approach the GNOME team is working on is Sarma, an online editor with Doc Book XML, and CVS, along with the installation of some additional software packages.

Doxygen
"Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

It can help you in three ways:

1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX} from a set of documented source files. There is also support for generating output in RTF (MS-Word), Post Office.org documents into Doc Office.org as an editor for Doc Office.org file into Doc Book XML. This script also makes it possible to manage images included in the document, using ole2img and pyUNO to export OLE objects as images."

Translated from the French

A Distributed Content Model for Developer Documentation
(This was introduced to FDP in this mail list posting . The follow thread starts in this message .)

"The OSDL DTL Technical Board (organized) an IRC session on developer documentation. This (was) a follow up to discussions that took place on the first OSDL Desktop Architect Meeting and in preparation of DAM III  where we would like to move this topic forward.

At the first Desktop Architects meeting (Dec, 2005) it was found that ISVs have difficulty finding documentation, and choosing between alternative libraries and tools. ISVs would like a site with complete, up-to-date, high-quality Linux documentation. They need roadmaps (perhaps more than one). There's a lot of misleading documentation out there which discusses deprecated interfaces as if they were preferred; the site should help people avoid those.

A key concern raised with respect to any portal is the maintenance burden. The only viable way to guarantee that information in a development portal is kept up to date is through a strong relation with upstream projects that can provide key information with authority.

Another requirement to take into account is the desire of OSVs to point their customers to a company site that reflects more closely their products instead of a third party site.

The above requirements hint towards a distributed content model that facilitates multiple distinct content owners with a feedback mechanism to route feedback back to the authorative content owner. It may be that the solution to the documentation problem will not be so much a single documental portal but more so a standardized documentation infrastructure that the various stakeholders can tap into; as a consumer of content, as a provider of content, or as a combination of the two.

See http://developer.osdl.org/dev/desktop_architects/index.php/Key_Topics#Developer_Portal for more information.

-