Re: Mallardized Tetravex manual

[Mario Blättermann <mariobl gnome org>]

Am Dienstag, den 03.11.2009, 20:00 -0600 schrieb Shaun McCance:
> On Mon, 2009-11-02 at 20:02 +0100, Mario Blättermann wrote:
> > Hi,
> > here is the first draft of the Tetravex manual in Mallard. As said, a
> > 1:1 copy of the existing docs. I have still a problem: The weblink in
> > license.page doesn't work. What's the matter here?
> 
> Hi Mario,
> 
> Thanks for working on this.  We've generally taken the approach
> of starting from scratch on Mallard documents.  This is for two
> reasons.  First, topic-based help involves a different way of
> thinking about the information you present.  If you start from
> a manual, it will influence how you write.  Second, we've been
> transitioning our documents to CC-BY-SA 3.0.  Unless you hold
> the sole copyright on the work, the only way to relicense is
> to start from scratch.
> 
> We haven't done any game help yet, but my vague plans for most
> simple games is to start from two topics: an introduction and
> a strategy page.  The introduction ("Introduction" or "Gameplay",
> we can discuss that) tells you how the game is won and what you
> do to get there.  The strategy page lists various tips and tricks
> that can help you play better.  (Strategy pages, by the way, are
> a great place to solicit contributions from users.)
> 
> Note that we generally don't include information on how to start
> applications.  It's just not useful.
> 
> I'd also like to include an Accessibility page in most of our
> help.  For smaller documents, this can be standalone page; for
> larger documents, it may be a guide that links to additional
> topics.  We can work with the accessibility team to see what
> information they think would be useful in these pages.
> 

Hi Shaun,

many thanks for pointing this out.  As you know, I've translated the
Mallard docs (partially) into German.  Migrating the Tetravex manual was
just a playground for me to better understand how this new format works.

I'm involved in the gLabels project, and we are planning a new Mallard
documentation for gLabels-3.0, which is likely to come along with GNOME
v3.  The current DocBook manual is really complete, and it covers all
facts of the application, in the meaning of the good old DocBook style.
Including things such as "To close the window, click on close." I agree
with you, users don't need such a nonsense. That's why it is needed to
write it from scratch, even I get the agreement from the original
author. 

But doc writers need an information pool for all things assigned to the
topic-based style.  There have to be basic rules, as these you've
described for game manuals above. The question is, where to place them?
The current docs-docs (such as the GDP handbook, the g-d-u migration
manual, or the XSLT manual) are outdated anyway. In my mind, the Mallard
docs could be a good place for that.  It should be the information
source for all things related to documentations, both technical and
style aspects.  Would be a good idea to rename it to "Documentation
handbook" once it can fulfill this purpose.

By the way, if we don't mention how to start an application, shouldn't
it be good to list command line options, if any? These could appear as a
link at the index page, in the "see also" section, because they are not
intended to the beginner, only for experienced users.  If a manpage
exists, the link could target to this, since Yelp can handle it.


Cheers,
Mario