[Desktop_architects] REMINDER: OSDL DTL Tech Board:Documentation Framework (Tue, Oct 17)

[Bastian, Waldo]

>On Tuesday 17 October 2006 18:41, Dominik Haumann wrote:
>> On Tuesday 17 October 2006 16:57, Bastian, Waldo wrote:
>> > About to start!
>>
>> I wasn't able to join the channel in time. Are there any notes or irc
>logs
>> I can read?
>
>I've attached my IRC log.
>
>It is a very big project if you ask me and it is still very vague(not
that
>I would expect anything else at this point).

Distilled version below:

Executive Summary

Common practices for documentation and usage of metadata could allow
more effective use of existing documentation efforts. A set of useful
metadata should be defined. Linux magazines should be engaged to see if
it is viable to use magazine content as part of Linux platform
documentation on a structural basis.

Participants:
<FransE> I'm Frans Englich, KDE and XML hacker. My interest in this is
rather general; I'd like to see a doc. solution for GNOME, KDE and all
the other open source projects out there.
<cherry> I'm John Cherry and I am the OSDL Desktop Linux (DTL)
initiative manager.  Developer documentation is one of those topics that
always comes up in the development community, but noone has the budget
or bandwidth to make it happen. Part of the problem is pulling
documentation together from across distributions and commuity
organization.  A daunting task.
<wbastian> I am Waldo Bastian, chairman of the OSDL Desktop Linux (DTL)
tech board. In DTL's quest for Linux deskop world domination the data
points to application availability as a major barrier to adoption... to
overcome that it is important to make the platform attractive for ISVs.
Presenting Linux as a single platform to ISVs is an important aspect of
that... given Linux's relative small market segment share any
fragmentation detoriates ISV interest in the platform rapidly
<ghopper> I am Gordon Hopper, a software engineer.  I'm a big fan of
open source software and Linux, but the fragmentation makes it confusing
to sell to my bosses.

Links
http://englich.wordpress.com/2006/10/17/open-source-documentation-framew
ork/
http://live.gnome.org/ProjectMallard
http://www.freestandards.org/en/Developers
http://www.opensearch.org/
http://developer.osdl.org/dev/desktop_architects/index.php/Key_Topics

Summary

Good documentation of the Linux platform remains a challenge. Many
projects struggle to find enough volunteers to write new documentation
or update existing. A way to improve the situation would be to make more
efficient usage of existing documentation efforts which, as a side
effect, would make it more interesting to invest in such documentation
efforts.

A distributed documentation framework was discussed that would help
making more effective use of documentation. Early ideas for such a
system center around a docbook based content model with extensive usage
of metadata for tagging purposes and RSS style feeds to publish update
and change information. The distributed model would consist of content
publishers, typically open source projects, and content consumers,
typically some kind of developer portal. The update feeds would inform
portals about new content or changes to existing content that the portal
can then (re-)fetch. A portal would be able to subscribe to multiple
feeds from different providers.  A portal would typically take the
docbook based content and transform it to HTML based on a portal
specific stylesheet.

Users of the portal would be able to search portals based on traditional
text based searches, but additional metadata would allow the quality of
searches to be improved.

A problem with existing documentation (of the howto style) is that it is
often not clear how up to date or relevant it still is. Ideally
documentatin should be reviewed at regular intervals by someone
authoratitive in the project for which it is written. It would be useful
to capture in metadata when a piece of documentation was last reviewed
and by whom.

With a distributed content model (like we have today already) it is also
important to route feedback or corrections back to the responsible
party. Again metadata can be used here to point to an upstream issue
tracker suitable for collecting such feedback.


The framework will depend on a certain uniformity of the content, for
example content may need to be in docbook format.

Today, a lot of "howto" style articles are being written for various
Linux magazines. It would be interesting to explore working together
with these publishers to find a way to better leverage these articles as
documentation for the Linux platform by hooking it into the outlined
documentation framework.

A documentation framework would also benefit from the ability to map
versions of specific software components to specific distribution
versions and/or LSB versions, some of this information is toay already
available from distrowatch. Also mapping higher-level concepts to
specific components would be helpful since people may not always know
what they are looking for.

A critical aspect of a distributed documentation framework seems to be
the definition of a common set of metadata to tag content with.

Action Items & Next Steps

* Engage linux magazines to get their perspective and interest to
participate
* Draft a set of metadata to tag documentation with
* Next irc meeting on November 14 to discuss metadata draft
* Followup discussion on
https://lists.osdl.org/mailman/listinfo/desktop_architects

Waldo Bastian
Linux Client Architect - Client Linux Foundation Technology
Channel Platform Solutions Group
Intel Corporation - http://www.intel.com/opensource
OSDL DTL Tech Board Chairman