Improving the Docs Project workflow - Innovative Approaches

From FedoraProject

Jump to: navigation, search

Contents

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 DocBook format, inside a MoinMoin-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 DocBook XML format. Much progress has been made, with the goal to merge the code with the upstream MoinMoin 1.6 release.

Sarma

One new approach the GNOME team is working on is Sarma, an online editor with DocBook XML import and export support. CVS commits are handled automatically. Refer to http://live.gnome.org/LiveDocumentationEditing for further details. However, this project hasn't been touched in over three years.

This is in contrast to our current approach, which requires knowledge of an editor like Emacs, DocBook 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), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

3. You can even abuse' doxygen for creating normal documentation (as I did for this manual) [reference is to online doxygen manual] ."

OOo2DBK

OOo2DBK "converts Open<code>Office.org documents into DocBook XML. The OOo2DBK package gives access to a set of tools which makes it possible to use OpenOffice.org as an editor for DocBook documents.

The ooo2dbk Python script allows the export of an OpenOffice.org file into DocBook 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.


Previous Page - Advancing the Project Table of Contents Next Page - GNOME Tools