After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 338122 - [aisleriot] suggestions for games help pages
[aisleriot] suggestions for games help pages
Status: RESOLVED OBSOLETE
Product: aisleriot
Classification: Other
Component: docs
git master
Other All
: Low enhancement
: ---
Assigned To: Maintainers of Gnome user documentation
Maintainers of Gnome user documentation
Depends on:
Blocks:
 
 
Reported: 2006-04-11 18:52 UTC by Amnon Aaronsohn
Modified: 2021-06-02 11:31 UTC
See Also:
GNOME target: ---
GNOME version: 2.13/2.14



Description Amnon Aaronsohn 2006-04-11 18:52:35 UTC
I think that the instructions for each game could be friendlier. Here are a few
suggestions:

* In the "Setup" section for each game, remove or reword the text beginning with
"Deal..." (the text referring to how the cards are dealt initially) because it
looks like playing instructions. In some of the games it says "the cards are
dealt..." instead of "Deal...", which is better, by I'm not sure if this part is
necessary at all, since as soon as the game begins the player can see how the
cards are arranged.

* Replace the "Setup" section with a graphical description (i.e. picture) of the
playing window. 

* Add links to the glossary from terms such as "building up", because the
glossary isn't visible when the help window is opened, and the user probably
doesn't even know that there is a glossary. Even better, pop up a box explaining
the term when the mouse hovers over it, tooltip-style.

* Add a button that opens the current game's help page to the toolbar.


Other information:
Comment 1 Alan Horkan 2006-04-24 12:53:13 UTC
[No huge changes are likely unless you are volunteering to help make them happen but smaller are reasonably likely]

(In reply to comment #0)

> * Replace the "Setup" section with a graphical description (i.e. picture) of
> the playing window. 

Maintaining screenshots in documentation is not fun, so much so that groups like Sun Microsystems have a policy of not putting screenshots in the documentation at all if it can be avoided (and that policy has been passed on to most of Gnome).  

If Gnome-games included a way to write out the main drawing area as a GdkPixbuf image it might make it easier to automate the process (probably a command line option to export a PNG file at a small size)

> * Add links to the glossary from terms such as "building up", because the
> glossary isn't visible when the help window is opened, and the user probably
> doesn't even know that there is a glossary. 

Having seen the extensive linking to the glossary in the documentation of goodsol (a windows shareware solitaire program) this is certainly a good idea and something I have considered doing myself eventually.  Patches to the documentation helping with this would be very much appreciated.  

> Even better, pop up a box explaining the term when the mouse hovers over it, tooltip-style.

The Gnome help browser (yelp) doesn't support this as far as I know, so you might want to file a seperate request for this feature to be supported first.  

> * Add a button that opens the current game's help page to the toolbar.

I think there may be a reason this wasn't done already.  
Help is slow to open so you might not want to accidentally click on it.  
This is relatively easy to add if the developers do want it.  


Some good suggestions here, moving out of Unconfirmed state.  hopefully developers will add their opinions on which of these changes they are most interested in.  
Comment 2 Amnon Aaronsohn 2006-04-24 18:14:21 UTC
(In reply to comment #1)
> > * Replace the "Setup" section with a graphical description (i.e. picture) of
> > the playing window. 
> 
> Maintaining screenshots in documentation is not fun, so much so that groups

Another option is to put a more schematic view of the playing surface (simple rectangles instead of cards/slots). This will probably need much less maintanance than screenshots.
  
Comment 3 Richard Hoelscher 2006-04-24 18:59:52 UTC
I don't think screenshots will be very useful in solving these problems... Clearly marking tableaus, draw piles, and such, as well as adding tooltips and/or status bar messages that explain how the slots are used, would be better in the long run. 

Technically, though, it isn't something that could be implemented immediately, as aisleriot's user interface is not currently supplied with information about the behavior (draw pile? etc.) of the various slots until a user performs a specific action on them.
Comment 4 Joachim Noreiko 2006-11-11 11:05:00 UTC
Moving to correct component.

(This is the problem with having only one component for docs -- see Bug 339173)
Comment 5 Joachim Noreiko 2006-11-12 10:44:00 UTC
(In reply to comment #0)
> * In the "Setup" section for each game, remove or reword the text beginning
> with
> "Deal..." (the text referring to how the cards are dealt initially) because it
> looks like playing instructions. In some of the games it says "the cards are
> dealt..." instead of "Deal...", which is better, by I'm not sure if this part
> is
> necessary at all, since as soon as the game begins the player can see how the
> cards are arranged.

I agree that 'Deal' looks like an instruction.
I think 'The cards are dealt...' is a good way to put it.
A lot of the individual game pages could do with polishing, as they can be quite wordy. But even this small change will be a big job, as there are so many of them.
Any budding documentation writers want to submit patches for a few at a time?

> * Replace the "Setup" section with a graphical description (i.e. picture) of
> the
> playing window. 

A diagram wouldn't need maintaining in the future, as the rules of the game aren't going to change. But one for each game is a LOT to do, and each one would need translating.
Also, the user would still need to be switching between the application and the manual to connect the parts of the game to the diagram.
I'd rather the maintainers of aisleriot look at ways to describe the parts of the playing area.

> * Add links to the glossary from terms such as "building up", because the
> glossary isn't visible when the help window is opened, and the user probably
> doesn't even know that there is a glossary. Even better, pop up a box
> explaining
> the term when the mouse hovers over it, tooltip-style.

Glossary links will one day be fairly easy to do: see bug 334314.
In the meantime, the best we could do is put a link to the glossary on each game page. Again, a lot of work and I'm not sure how it would look as it would be a link to the whole glossary page, not the individual term.

> * Add a button that opens the current game's help page to the toolbar.

The Help menu has an item that opens the gurrent game's help page. You can file a bug on the app if you think a toolbar button is needed too.

SUMMARY:
- Patches welcome for the 'Deal'/'Cards are dealt' thing.
- I'll look into making it clearer that the glossary exists.

Comment 6 André Klapper 2013-02-23 11:30:25 UTC
Still valid in current docs at http://help.gnome.org/users/aisleriot/unstable/
Comment 7 Aruna Sankaranarayanan 2013-04-22 16:08:01 UTC
I am working on this. Have fixed the help for about 10 games. Will fix all and upload a patch. :)
Comment 8 Vincent Povirk 2013-04-22 16:16:19 UTC
Maybe you should send what you have now so it can be reviewed, rather than do a lot of work that you potentially have to change.
Comment 9 Kat 2013-04-22 17:38:22 UTC
(In reply to comment #8)
> Maybe you should send what you have now so it can be reviewed, rather than do a
> lot of work that you potentially have to change.

The current help is licensed under GFDL, which the docs team do not feel is free enough to be used for user help as it can be a bit awkward to comply with. To make changing to CC-by-SA problem-free, and to change the tone of the help to be task oriented and consistent with other user help, it is better if the old help is not looked at before the rewrite. We generally do, of course, check that we haven't missed anything after the bulk of the rewrite is done.

Of course, the docs team will do reviews of the help as Aruna works her way though it. If she is accepted for the Outreach Program for Women, there is a good chance that she may be completing this work as part of her internship.
Comment 10 Christian Persch 2013-04-22 18:09:41 UTC
(In reply to comment #9)
> The current help is licensed under GFDL, which the docs team do not feel is
> free enough to be used for user help as it can be a bit awkward to comply with.

  ^^^^ non-free, you mean. CC is *not* a free licence; GFDL and GPL are free.

> To make changing to CC-by-SA problem-free, and to change the tone of the help

For the new material, a dual licence (GFDL + CC) or tri-licence (GFDL + GPL3+ + CC) is acceptable; a pure CC licence is not.

> [...] and to change the tone of the help
> to be task oriented and consistent with other user help, it is better if the
> old help is not looked at before the rewrite. We generally do, of course, check
> that we haven't missed anything after the bulk of the rewrite is done.

There are substantial amounts of work represented in the existing translations, where https://l10n.gnome.org/module/aisleriot/ shows 11 languages with quite good coverage. I worry that with a rewrite (esp. for the ~90 ! per-game help pages), this work will needlessly be thrown away...

So changes should represent a substantial improvement to be worthwhile. The generic help certainly qualifies, but I'm not so sure about the per-game help pages.
Comment 11 André Klapper 2013-04-22 20:28:10 UTC
(In reply to comment #10)
> For the new material, a dual licence (GFDL + CC) or tri-licence (GFDL + GPL3+ +
> CC) is acceptable; a pure CC licence is not.

IANAL (I am not a lawyer), but in my opinion you can only dual-license GFDL **version 1.3** with CC licenses (though GFDL1.3 Section 11 is actually meant for manuals that are wikis, according to James Vasile who worked on GFDL 1.3).
I don't see how to apply GPL to documentation.

If you plan to relicense you'll also have to check translation files and contact translators to get their okays (preferably explicitly and in a public place).
Comment 12 Christian Persch 2013-04-22 20:40:01 UTC
The *whole* thing could obviously only be under a multi-licence if the existing parts are either removed (what commen 9 is proposing) or relicensed. However meanwhile *new* parts can of course be added under a "either X or Y or Z" licence, which when combined with the existing parts only leave the compatible licence for now (GFDL).
Comment 13 Kat 2013-04-22 20:40:34 UTC
(In reply to comment #10)
> (In reply to comment #9)
> > The current help is licensed under GFDL, which the docs team do not feel is
> > free enough to be used for user help as it can be a bit awkward to comply with.
> 
>   ^^^^ non-free, you mean. CC is *not* a free licence; GFDL and GPL are free.

I mean that it makes most sense to allow the most people to distribute the help and reuse it with as few restrictions as possible while giving the authors credit. CC gives more freedom to do this than GFDL as the GFDL has more restrictions on how the work can be reused.

As it is, library.gnome.org breaches the terms of the GFDL for aisleriot (the full text of the license is not included anywhere and the license is not included when the help is printed) and aisleriot help does not use the licence properly (at least some of the individual help documents do not include the notice). This is just one example of what I mean by this being a difficult license to comply with.

> For the new material, a dual licence (GFDL + CC) or tri-licence (GFDL + GPL3+ +
> CC) is acceptable; a pure CC licence is not.

CC + GPL3 would be an acceptable compromise, as before, but this would still mean that we cannot reuse other help in aisleriot (which, if I am really honest, we do all the time) without relicensing.
 
> > [...] and to change the tone of the help
> > to be task oriented and consistent with other user help, it is better if the
> > old help is not looked at before the rewrite. We generally do, of course, check
> > that we haven't missed anything after the bulk of the rewrite is done.
> 
> There are substantial amounts of work represented in the existing translations,
> where https://l10n.gnome.org/module/aisleriot/ shows 11 languages with quite
> good coverage. I worry that with a rewrite (esp. for the ~90 ! per-game help
> pages), this work will needlessly be thrown away...
> 
> So changes should represent a substantial improvement to be worthwhile. The
> generic help certainly qualifies, but I'm not so sure about the per-game help
> pages.

I personally consider bringing the help in line with the rest of the GNOME help a worthwhile effort and once it has successfully been through a full review process, I find the quality is higher.

A rewrite would indeed need a full retranslation. On the other hand, if the current help was fully reviewed, there would likely be enough changes to it that large chunks of it would need to be retranslated, so I think that a rewrite is unlikely to be more effort than a review.
Comment 14 Christian Persch 2013-04-24 11:19:49 UTC
(In reply to comment #13)
> (In reply to comment #10)
> > (In reply to comment #9)
> I mean that it makes most sense to allow the most people to distribute the help
> and reuse it with as few restrictions as possible while giving the authors
> credit. CC gives more freedom to do this than GFDL as the GFDL has more
> restrictions on how the work can be reused.

I accept (even if I disagree with it) that the docs team has chosen CC. OTOH, I as maintainer insist on free software, not "open source", hence GFDL or GPL (preferably both) :-)
 
> As it is, library.gnome.org breaches the terms of the GFDL for aisleriot (the
> full text of the license is not included anywhere and the license is not
> included when the help is printed) 

Hmm that's certainly something we should fix. Is this a problem on the aisleriot side (full licence text not xincluded) or on the lib.g.o side ?

> and aisleriot help does not use the licence
> properly (at least some of the individual help documents do not include the
> notice). 

If this is about the individual .xml documents, then lack of copyright header is acceptable as long as it's clear they're under GFDL (which I think it is clear, since the main doc says so, and the licence text is included in the repo).

> I personally consider bringing the help in line with the rest of the GNOME help
> a worthwhile effort and once it has successfully been through a full review
> process, I find the quality is higher.
> 
> A rewrite would indeed need a full retranslation. On the other hand, if the
> current help was fully reviewed, there would likely be enough changes to it
> that large chunks of it would need to be retranslated, so I think that a
> rewrite is unlikely to be more effort than a review.

Thinking about this some more, I think you're right. And for the per-game help pages, which have been written over time by different people and thus use  different words and phrases from one to the next. It would be great to develop a 'vocabulary' of phrases to use in the per-game help, so that they could be uniform in style, and by re-use make translator's job much easier and smaller.

For the main, game-independent part of the help, the only complication is that I'm not sure yet if we'll get the aisleriot re-design (bug 697135) in for 3.10 or not.
Comment 15 Kat 2013-05-19 13:25:52 UTC
(In reply to comment #14)
> (In reply to comment #13)
> > As it is, library.gnome.org breaches the terms of the GFDL for aisleriot (the
> > full text of the license is not included anywhere and the license is not
> > included when the help is printed) 
> 
> Hmm that's certainly something we should fix. Is this a problem on the
> aisleriot side (full licence text not xincluded) or on the lib.g.o side ?
> 
> > and aisleriot help does not use the licence
> > properly (at least some of the individual help documents do not include the
> > notice). 

> If this is about the individual .xml documents, then lack of copyright header
> is acceptable as long as it's clear they're under GFDL (which I think it is
> clear, since the main doc says so, and the licence text is included in the
> repo).

It is both to some extent:
The licence blurb (which is not the official, recommended one) is not included in every file.
l.g.o distributes the help independently of the source: this means that the full licence text is not distributed via l.g.o.

Because the full licence is not in legal.xml, it is difficult for users to comply with the licence when they print the help in yelp and from l.g.o.

If the full licence text is included in legal.xml, then there will not be any problems with yelp and at least the full licence will be distributed trough l.g.o instead.

I would argue that each *.xml file can be distributed individually, so it should be safer to link to legal.xml from each *.xml file. I do not see any harm in this and it would help cover all cases.

> It would be great to develop
> a 'vocabulary' of phrases to use in the per-game help, so that they could be
> uniform in style, and by re-use make translator's job much easier and smaller.

Agreed, the right place for this (for the moment) is on live.gnome.org.

> For the main, game-independent part of the help, the only complication is that
> I'm not sure yet if we'll get the aisleriot re-design (bug 697135) in for 3.10
> or not.

That will be good to keep in mind.
Comment 16 GNOME Infrastructure Team 2021-06-02 11:31:54 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/aisleriot/-/issues/69.