Project Mallard

ProjectMallard is the DocumentationProject's long term project.

Contents

  1. Project Mallard
    1. Introduction
    2. The competition
      1. The entries
    3. A documentation licence
    4. A Markup Language
      1. Beyond DocBook
      2. Pitfalls
      3. Help from different sources
    5. Kill scrollkeeper using a blunt knife^W spoon

Introduction

Our documentation system currently has some shortcomings that cannot be overcome without a complete overhaul from the ground up. To this end several things must come together:

Shaun's original notes on this: http://www.gnome.org/~shaunm/quack/mallard.xml

What's in the Mallard

This is a list of projects roughly grouped into the Mallard name:

The idea is that all of these should be developed together. This will allow all the components to work well together, instead of (e.g.) an editor that is shoe-horned into working with a current system and doesn't fit as well. It also means the doc reading and writing procedure is more fluid and fits better together.

The competition

You can be forever immortalized by having named the XML format that will take over the desktop documentation world. A decade from now, an aspiring young technical writer will be learning this format in college, as it will then be the industry standard. And she'll be chatting with her professor, and her professor will say, "When I was your age, we didn't have $FORMAT. And we had to walk uphill in snow over broken glass to get to our text terminals to write documentation in DocBook. But that all changed when $PERSON galvanized the industry by naming $FORMAT."

The entries

Add your ideas for a name for these projects below !

A documentation licence

Which licenses are appropriate for documentation of gnome projects? Which are the pros and cons. Are there conflicts?

Licences:

After issuing

I found out that I have 399 documents installed which are all under the GFDL. A bit scary is the fact that 333 of them have "Sun Microsystems" as the copyright holder. Would be nice if author would not just copy the omf file, but also put their names in there. Many of the docs are translations. What is the suggestion for the translator name. Should they just append their name to the copyright holders?

A Markup Language

The format is XML, as $DEITY intended. Here's what you get:

1) The pages you see in Yelp are exactly the pages you write. Yelp won't have to look at a deep section hierarchy and try to figure out the most logical way to present chunked information to the user.

2) The pages each stand on their own. They are not part of a linear structure. Instead, they are linked into nodes that help users navigate and find information.

3) There will be maybe 10-15 block-level elements, with very clear semantic purpose and with reasonably well-specified presentation.

4) There will be exactly one table model, and it will be the one you get with HTML. CALS tables kill kittens.

5) There will be maybe 10-15 inline elements, with very clear semantic purpose. You know how, in DocBook, you have to hunt through 50 or so inline elements, and then there are maybe five that sort of closely match what you're trying to mark up? Or you have to use systemitem because there's not a specific element for your needs, but then that feels dirty because there are *very* specific elements for other things. Let's stop the insanity.

6) The presentational behavior of all automatic text will be specified very very very exactly. It has a huge impact on how you write your document, and you deserve to know what a processor is going to do with your text.

7) The format is simple enough that sophisticated editors will not be difficult. Writing a wiki-esque thing to do online editing should be easy enough. If people really like that workflow, then we can work towards that. What I don't believe in is converting presentational markup to semantic markup. I don't think anything short of natural language parsers have any hope of getting the conversion right.

8) Documents are pluggable. I can't even begin to explain just how cool this one bullet point is.

Beyond DocBook

DocBook does things we don't need it to, and it can't do some things we want to do. What are they?

We want:

We might want:

package X is installed, whether package X is not installed, whether you are an administrator, and so on.

Pitfalls

Mallard would resolve problems such as not knowing which screensaver the next version of GNOME will ship with (this happened with 2.14). We'd write a section with id 'x-screensaver', and one 'gnome-screensaver', and the help buttons would find the right one. But... what if elsewhere in the docs we want to say 'The Lock Button starts the screensaver (LINK)'. We don't know which link ID to use. How do we get round that?

Help from different sources

Distros such as Ubuntu write their own User Guides. This then intersects with our own User Guide, creating a confusing front for the user. Could there be a way for Mallard to integrate these?

Kill scrollkeeper using a blunt knife^W spoon

Scrollkeeper is the document registration system for GNOME and Yelp. It tells yelp where to look for your documents. It has a few problems.

There are a couple of possible alternatives:

  1. Fork scrollkeeper and make changes ourselves, fixing most of the major problems

  2. Start from scratch, but offer backwards compatibility tools: Spoon is an attempt at this with its name taken from the title

GDP-logo-tmp.png

This page belongs to the GNOME Documentation Project series, it concerns writing documentation for GNOME. Perhaps you can help out, or would like to consult the GNOME documentation.

CategoryDocumentationProject

ProjectMallard (last edited 2008-02-03 14:45:31 by localhost)