Mallardized Tetravex manual

[Mario Blättermann-3]

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?

Cheers,
Mario


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Milo Casagrande-3]

Hi Mario,

thanks for your work porting documents to Mallard!

2009/11/2 Mario Blättermann <mariobl@...>:
> 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?

For the web link in the license page, use:
<link href=""></link>

instead of:
<link type="http" url=""></link>

No type attribute is defined for inline Mallard link (mal_inline_link)
element. You use the type attribute only with link in the info section
of a page (mal_info_link).

Also, but that's not really a problem, only Yelp complaining, there is
no address, street, state (and the others too) element in Mallard.
Maybe you can use a code block to represent the FSF address.

Hope this can help.

Ciao.

--
Milo Casagrande <milo@...>
_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Mario Blättermann-3]

Am Montag, den 02.11.2009, 20:52 +0100 schrieb Milo Casagrande:

> Hi Mario,
>
> thanks for your work porting documents to Mallard!
>
> 2009/11/2 Mario Blättermann <mariobl@...>:
> > 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?
>
> For the web link in the license page, use:
> <link href=""></link>
>
> instead of:
> <link type="http" url=""></link>
>
> No type attribute is defined for inline Mallard link (mal_inline_link)
> element. You use the type attribute only with link in the info section
> of a page (mal_info_link).
>
> Also, but that's not really a problem, only Yelp complaining, there is
> no address, street, state (and the others too) element in Mallard.
> Maybe you can use a code block to represent the FSF address.
>
> Hope this can help.
>

Yes, it helps really:-)

New license.page is attached.

Another question: I get the topics in index.page in a wrong sort order.
Like this:

Customization
Introduction
License
Playing GNOME Tetravex

But I want to have:

Introduction
Playing GNOME Tetravex
Customization
License

How I can get this?


Cheers,
Mario

Legal Information.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

Free Software Foundation, Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA
_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Milo Casagrande-3]

Hi Mario,

2009/11/2 Mario Blättermann <mariobl@...>:
> Yes, it helps really:-)

Happy it helped!

> New license.page is attached.
>
> Another question: I get the topics in index.page in a wrong sort order.
> Like this:
>
> Customization
> Introduction
> License
> Playing GNOME Tetravex
>
> But I want to have:
>
> Introduction
> Playing GNOME Tetravex
> Customization
> License
>
> How I can get this?

For how I undertand things (actually I can't remember if I asked Shaun
about this...), the sorting of that page is based on the titles of the
linked pages. So that's going to be a little bit hard to adjust the
sorting as long as you don't change the words you use.
What you can do instead, is "thinking" a little bit different the
layout of your help. Thinking a little bit more topic-based.

I'm attaching a simple 2-minutes hack based on what you have done.
Take a look at it and see if it can work for you. It can be adjusted
and probably expanded too.

Ciao.

--
Milo Casagrande <milo@...>


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Jim Campbell-4]

2009/11/2 Milo Casagrande <milo@...>

Hi Mario,

2009/11/2 Mario Blättermann <mariobl@...>:

> Yes, it helps really:-)

Happy it helped!

> New license.page is attached.
>
> Another question: I get the topics in index.page in a wrong sort order.
> Like this:
>
> Customization
> Introduction
> License
> Playing GNOME Tetravex
>
> But I want to have:
>
> Introduction
> Playing GNOME Tetravex
> Customization
> License
>
> How I can get this?

For how I undertand things (actually I can't remember if I asked Shaun
about this...), the sorting of that page is based on the titles of the
linked pages. So that's going to be a little bit hard to adjust the
sorting as long as you don't change the words you use.
What you can do instead, is "thinking" a little bit different the
layout of your help. Thinking a little bit more topic-based.

I'm attaching a simple 2-minutes hack based on what you have done.
Take a look at it and see if it can work for you. It can be adjusted
and probably expanded too.

Ciao.

I think I noticed this same issue on the Empathy help as displayed in Yelp.  One of the help sections displays the topics in an order that doesn't make logical sense (I think it was the second main section, perhaps about creating an account or chatting via IRC). 

I understand that topic based help is supposed to document individual chunks of information to the user, and that these chunks should be able to stand-alone, but it still seems necessary to present those topics in a logical order.  Otherwise, it's confusing to the user.  Suggesting that users think about the help differently doesn't really help them.

Milo, is your "hack" to list the preferred order of the other .page files from within the index.page file?  That's wha it seems like you are doing in the example you provided.

Jim

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Milo Casagrande-3]

Hi Jim,

2009/11/3 Jim Campbell <jwcampbell@...>:
>
> I think I noticed this same issue on the Empathy help as displayed in Yelp.
> One of the help sections displays the topics in an order that doesn't make
> logical sense (I think it was the second main section, perhaps about
> creating an account or chatting via IRC).

Yes, you are right.

> I understand that topic based help is supposed to document individual chunks
> of information to the user, and that these chunks should be able to
> stand-alone, but it still seems necessary to present those topics in a
> logical order.  Otherwise, it's confusing to the user.  Suggesting that
> users think about the help differently doesn't really help them.

I agree with you. This is something we probably need to discuss with
Shaun, maybe during (or after) the next team meeting (Sunday 8th
November).

> Milo, is your "hack" to list the preferred order of the other .page files
> from within the index.page file?  That's wha it seems like you are doing in
> the example you provided.

Yes, at the moment the only way to achieve some sort of ordering that
I know of is in that way. Still, topics in a section get sorted
alphabetically by their title.

Ciao.

--
Milo Casagrande <milo@...>
_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Shaun McCance-2]

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.

--
Shaun


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Shaun McCance-2]

On Mon, 2009-11-02 at 22:45 +0100, Milo Casagrande wrote:

> Hi Mario,
>
> 2009/11/2 Mario Blättermann <mariobl@...>:
> > Yes, it helps really:-)
>
> Happy it helped!
>
> > New license.page is attached.
> >
> > Another question: I get the topics in index.page in a wrong sort order.
> > Like this:
> >
> > Customization
> > Introduction
> > License
> > Playing GNOME Tetravex
> >
> > But I want to have:
> >
> > Introduction
> > Playing GNOME Tetravex
> > Customization
> > License
> >
> > How I can get this?
>
> For how I undertand things (actually I can't remember if I asked Shaun
> about this...), the sorting of that page is based on the titles of the
> linked pages. So that's going to be a little bit hard to adjust the
> sorting as long as you don't change the words you use.
> What you can do instead, is "thinking" a little bit different the
> layout of your help. Thinking a little bit more topic-based.

So currently, there's this system of link weights that you can
use to affect the ordering.  But it's fragile and not as useful
as I'd hoped, so I intend to remove it for 1.0.

You can affect the ordering with sort titles.  These are put
into the <info> element.  They're mostly intended for dropping
leading articles.  Something like this:

  <page>
    <info>
      <title type="sort">Quick Tour</title>
    </info>
    <title>A Quick Tour</title>
  </page>

I intend to add topic link grouping before 1.0.  I think Phil
suggested something along these lines, and I have a rough plan
for how to implement it.  But it's not in yet, so you can't
use it.

For a very small document like this one, I'd say it's OK to
abuse the sort titles for now.  Just give them sort titles
with numerical prefixes or something that effects the sort
order you want.

--
Shaun


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list

[Mario Blättermann-3]

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

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list@...
http://mail.gnome.org/mailman/listinfo/gnome-doc-list