Re: Can you take a look at my new patch?

[Tiffany Antopolski <tiffany antopolski gmail com>]

Hi Sophia, 

I had a look at your patch.  The patch is a direct copy of the DocBook documentation. This is not what we are looking for.  The DocBook documentation is a manual, meaning it is meant to be read from beginning to end for the user to gain an understanding of how the application works.  Mallard has a completely different style: it is designed to be topic-based help.  The idea is that while the user is using the app, if s/he is thinking "How do I ...", there should be a topic page that covers that one topic.  Each topic is generally quite short, with step-by-step instructions how to get the task done.  You want to be documenting these tasks, not how the entire program functions  -- unless it is part of how to get the task accomplished.  Also, often I find that the DocBook manuals document things that are quite obvious, like how to use a mouse (as an example).  Mallard help tries not to document things that the user can easily see for themselves.

The other problem is that most of the games manuals are out of date.  Since the time that they were written, the developers have changed some features, removed some, added some new ones, etc.  So the information contained within them may no longer be valid.  It is important, as a documentor, to check that all the information is valid.  Having said this, this doesn't seem to be the case for gnomine, except for the possible name change (GNOME Mines/gnomine?).  I just wanted to make you aware of this.

Another issue is that authors of code and documentation license their work under different licenses. For example, the DocBook documentation is licensed under GFDL/GPL (GNU Free Documentation License and General Public License), whereas the Mallard documentation is being licensed under CreativeCommons Attribution-Share Alike 3.0 Unported LIcense.  The two licenses are not compatible, meaning you can not take the work from the DocBook and copy it, without asking the original author to relicense the the original work under CreativeCommons Attribution-Share Alike 3.0 Unported License.  This is possible, by sending an e-mail to the original author asking for a license change, and cc-ing it to the doc-list.  However, the manual would still have to be re-written in topic based style, but you would be able to reuse some of the content.  Afterall, if it's good, why throw it away?

Screenshots would have to be retaken, as the ones in the DocBook use an old theme.

One thing you can do is compare the old Sudoku manual to the new Sudoku manual.  This is one example of where we did ask the original author for a change in license, he agreed, and we were able to reuse some of the material, giving him credit for the work.  But you will still see the manual is quite different. 

My recommendation at this point is to:
- come up with a set of topics that you think should be covered for gnomine (small tasks a user may want to know how to do).
- ask the original author for a licence change (if you feel all the information is correct and good and worth re-using).
- If the author agrees to a license change, you may be able to reuse some of his work.
- Either way, think of how to give clear concise (possibly step-by-step) instructions on how those tasks should be accomplished. 

At this time I have to reject the initial patch.  But hopefully you have a bit more information now for a second go.

Tiffany

On 16 December 2011 09:37, Tiffany Antopolski <tiffany antopolski gmail com> wrote:

Hi Sophia,

  Thanks for your patch. I did think that baptistemm was working on gnomine docs at the moment.   Don't worry, your patch won't be overlooked.  I can review it now if you would like, but  you should talk to baptistemm to coordinate. He (and I) are on #docs most of the time.

Cheers,

Tiffany

On 16 December 2011 02:44, Sophia Yu <sophia receiving gmail com> wrote:

Hi Jason,

I have submitted a new patch at https://bugzilla.gnome.org/show_bug.cgi?id=618343. Can you take a chance to look at it? Tiffany seems quite active recently on the Mallard documentation migration. I just don't want my patch overlooked and to be re-invented by others.

Thanks,

Sophia

--
Tiffany Antopolski

-- 
Tiffany Antopolski