Project Mallard
ProjectMallard is the DocumentationProject's long term project.
Contents
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:
- A documentation licence
- a markup language
- a standard place and way to keep docs
- the docs themselves: topic-based rather than monolithic documents. And cross-linked up the wazoo of course.
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:
- shaunm's mystical new language - much easier than docbook
- New documentation tracker system - allow us to see what's up-to-date, what needs doing and who's doing what
New metadata system - scrollkeeper sucks -- Spoon
New doc editor - A simple editor for doc writers and translators to make things easy and not have to deal with XML tags themselves (unless they want to) -- Foie Gras
A fresh look at the tone and style of our documentation: /DocumentationStyle
(Possibly) Project CodenameGraphite - an attempt to make a definitive reference guide for users and developers
(Possibly) GnomeWeb/Library - replace developer.gnome.org with something new and snazzy
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 !
- Eroteme - This is another name for a "question mark", sounded cool to me :o) - Karderio
- $FORMAT = Bob - And why not ? - Karderio
XHTML 2.0 (comment from GergelyNagy)
- will be _the_ standard (very) soon
- focuses highly on document structure
- allows custom modules for special needs (e.g. api tags for dev docs, etc)
- a lot of apps will support displaying it out-of-the box
- expect authoring tools too
- The competition is to provide a name for a new format, not to suggest a format to use. Please make this sort of suggestion on the docs list -- Joachim
- Pellucid - It expresses the aims of the markup style (clear/clean/transparent), and the desired clarity of meaning of the documentation itself.
A documentation licence
Which licenses are appropriate for documentation of gnome projects? Which are the pros and cons. Are there conflicts?
Licences:
GNU Free Documentation Licence GFDL
- Pros:
- Cons:
Debian will not redistribute: http://people.debian.org/~srivasta/Position_Statement.xhtml
After some debate, Debian decided that GFDL-licensed works without unmodifiable sections are free --LeonardoFontenelle
Effectively requires us to change the title all the time: http://mail.gnome.org/archives/gnome-doc-list/2005-October/msg00013.html
- The above description may not be accurate.
- The specific clause in GFDL protects us from people forking GNOME User Guide and calling it the same. This point in the license could be an issue if a documentation writer, who is the sole writer of a document or groups with all other writers of the same document, decides to leave and take with them the document title.
- This issue could be handled by giving the copyright/ownership/et al to a single body, such as the GNOME Foundation.
- This one has been resolved: new releases are considered to be new versions of the *same* document, and the title can remain the same.
- Has revision history requirements that are difficult to satisfy for dynamic online documents.
- Collaborative editing typically considers that the document state between releases is draft. On actual release you add revision history. Users who download draft (live) versions might be considered excempt here?
- Is there a way for revision history to be added "automatically"?
Creative Commons Text CC
- Pros:
- Cons:
- Many choices might create confusion.
Debian will not redistribute (except Public Domain): http://people.debian.org/~evan/ccsummary
FreeBSD Documentation License license text
- Pros:
- Clearly free to anybody.
- Cons:
- Might not be "copyleft" enough for all.
Needs minor modifications (to not to mention FreeBSD project and SGML DocBook).
- Pros:
- GNU General Public License:
- Pros:
- No known problems.
- Same as in the source code (in GNOME context).
- Cons:
- Is about Program, not Manual nor Documentation; concept of source code is unclear.
- Pros:
Open Publication License http://www.opencontent.org/openpub/
After issuing
- find /usr/share/omf -name "*.omf" -exec grep -o 'rights .* holder=\".*\" li' {} \; | cut -f2,3 -d" " | sort | uniq
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?
Yes; a translation is a derivate work. Maybe the translator should be listed in a "translators" part of the authors list. --LeonardoFontenelle
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:
- a simple way of marking things for translators
- for something that needs to stay literal and should never be translated: shouldn't be extracted to po files
- for something that isn't ready to translate yet
- markup for terminal commands
- markup for gui elements that have names rather than static labels. Eg: the parent folder selector
- a simple way for distros to replace and override parts of documents to reflect things that they have changed in GNOME: eg choise of spatial/browser default, name of main menu items, etc.
We might want:
- funky transclusion? Eg, User Guide has section on standard File Open dialog. Other apps add elements to this. App Foo's manual could embed the standard stuff, adding the extras particular to the app.
- conditional blocks based on whether
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?
DonScorgie: Two ways:
- Both screensaver sections / documents would have the same id. The metadata system would then know which is newer (based on a version field?)
- The metadata file description of the newer section (gnome-screensaver) would have a "replaces" field (replaces=x-screensaver). When yelp requests "sect=x-screensaver" from it, it automagically returns the "gnome-screensaver" section.
Both ways rely heavily on the metadata system being better than it currently is (*cough*Spoon*cough*)
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?
- Looking at the Ubuntu Desktop Guide, there is actually not that much overlap between it and the GNOME User Guide. Mallard's notion of topic-based help would allow the two to intermingle quite nicely. We'd need some sort of flexible contents page, and for "next" and "previous" links to feed from that.
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.
- Yelp has to access it through a command-line interface, grabbing the output
- This output isn't a list of all the document titles, locations and descriptions or anything crazy like that. It is a temp file (e.g. /tmp/scrollkeeper-$USER/content.0) which yelp must then open and parse
- The temp file isn't a list of all the document titles, locations and descriptions or anything crazy like that. It is a list of categories with entries for doc titles and paths to omf files
- These omf files must then be opened in turn, the contents parsed again, finally yeilding the doc title, location and description
- It doesn't understand languages that it isn't translated into. E.g. i a Spanish doc is registered through scrollkeeper, but scrollkeeper itself isn't translated into Spanish, it will silently fail
- The code is (seemingly) needlessly complex for what it does
It only handles omf files if they are installed in <prefix>. Installing a new program in your home directory won't make it show up in Yelp, without some serious dark-magic, if scrollkeeper is installed in /usr (default).
- Registration process at install time is a) slow and b) a pain for doc writers, packagers, maintainers, tool maintainers, translators and virtually everyone else
- It is unmaintained. At all. Not even bug fixes
- We are maintaining 3 patches for various seg faults just now. We get lots of bugs about these
- (from the TODO file in scrollkeeper) Registering an updated document won't overwrite a previous version. It will add a new doc to the index, leaving 2 copies of the same doc (potentially) on the system.
- It is missing a few features it would be nice to have
There are a couple of possible alternatives:
- Fork scrollkeeper and make changes ourselves, fixing most of the major problems
Start from scratch, but offer backwards compatibility tools: Spoon is an attempt at this with its name taken from the title
|
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. |
