Improving the Docs Project workflow - 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
Book format, inside a Moin
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
Book XML format. Much progress has been made, with the goal to merge the code with the upstream Moin
Moin 1.6 release.
One new approach the GNOME team is working on is Sarma, an online editor with Doc
Book 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, Doc
Book XML, and CVS, along with the installation of some additional software packages.
"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
Script, 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 "converts Open<code>Office.org documents into Doc
Book XML. The OOo2DBK package gives access to a set of tools which makes it possible to use Open
Office.org as an editor for Doc
The ooo2dbk Python script allows the export of an Open
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
"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|