For anyone interested in working on this, you will first of course need to be familiar with the game,  so be sure to install 'quadrapassel', and play around for a bit.

To begin documenting:

1. You will need to first get the git version of the gnome-games.  To do so, in a terminal, type:  

git clone git://git.gnome.org/gnome-games

This will create a directory called gnome-games in your current directory.  (You may first need to install 'git' using your distributions package manager)

2. To view the current documentation:

cd gnome-games/quadrapassel/help/C/
yelp quadrapassel.xml

This documentation is out of date.  First, we would like to convert it to Mallard, and second, updates to the game have been made, so some features may have been removed, others may have been added.  

To view an example of Mallard docs for a gnome game, you could look at Iagno, or gnome-sudoku or gnomine.  These games (and their documentation) are also in the gnome-games directory.  

So to view the Iagno docs, you would cd into the Iagno/help/C directory.  There you will see many files with the .page extension.  To view the docs in yelp documentation viewer, type:

yelp index.page  

The index.page is the entry page into the docs (similar to html).  You can use the yelp command to open any of the pages (yelp <page name>)

You can view the mallard source by opening the page using your preferred text editor (like Gedit or vim).

It is a good idea to look at the Iagno, gnome-sudoku, or gnomine docs as an example of the topics and layouts.




To begin writing Mallard help for Quadrapassel, you will create .page files in the quadrapassel/help/C directory using a text editor.  Use the yelp command to view your creation, changes, and progress.

Some references:

http://projectmallard.org/about/learn/tenminutes.html
http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png

For a GWOP application, an index page with stub pages would be a good start.  By stub pages I mean incomplete topics, just to show an outline of the project. Perhaps one completed topic page (like introduction.page, or play.page).

----

Once you have some pages you would like reviewed, you will need to set up your git (if you haven't done so already)  --> http://book.git-scm.com/2_setup_and_initialization.html

Then for each new .page you have created type:

git add <new page name>

then type:

git commit -a -m "quadrapasse docs: start of Mallard docs"


Now you will want to create a .patch file:

git format-patch HEAD^

This will create a .patch file in your current directory.  This is the file you should attach to this bug.  Once it is attached, someone will review it and give you feedback.

Feel free to talk to members of the documentation team on #docs during your progress.  :-)

Hello, 
I have already started working on the bug, and I will send it too You as soon as I finish.
Sincerely, 
Elena Petrevska


(In reply to comment #1)
> For anyone interested in working on this, you will first of course need to be
> familiar with the game,  so be sure to install 'quadrapassel', and play around
> for a bit.
> 
> To begin documenting:
> 
> 1. You will need to first get the git version of the gnome-games.  To do so, in
> a terminal, type:  
> 
> git clone git://git.gnome.org/gnome-games
> 
> This will create a directory called gnome-games in your current directory. 
> (You may first need to install 'git' using your distributions package manager)
> 
> 2. To view the current documentation:
> 
> cd gnome-games/quadrapassel/help/C/
> yelp quadrapassel.xml
> 
> This documentation is out of date.  First, we would like to convert it to
> Mallard, and second, updates to the game have been made, so some features may
> have been removed, others may have been added.  
> 
> To view an example of Mallard docs for a gnome game, you could look at Iagno,
> or gnome-sudoku or gnomine.  These games (and their documentation) are also in
> the gnome-games directory.  
> 
> So to view the Iagno docs, you would cd into the Iagno/help/C directory.  There
> you will see many files with the .page extension.  To view the docs in yelp
> documentation viewer, type:
> 
> yelp index.page  
> 
> The index.page is the entry page into the docs (similar to html).  You can use
> the yelp command to open any of the pages (yelp <page name>)
> 
> You can view the mallard source by opening the page using your preferred text
> editor (like Gedit or vim).
> 
> It is a good idea to look at the Iagno, gnome-sudoku, or gnomine docs as an
> example of the topics and layouts.
> 
> 
> 
> 
> To begin writing Mallard help for Quadrapassel, you will create .page files in
> the quadrapassel/help/C directory using a text editor.  Use the yelp command to
> view your creation, changes, and progress.
> 
> Some references:
> 
> http://projectmallard.org/about/learn/tenminutes.html
> http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png
> 
> For a GWOP application, an index page with stub pages would be a good start. 
> By stub pages I mean incomplete topics, just to show an outline of the project.
> Perhaps one completed topic page (like introduction.page, or play.page).
> 
> ----
> 
> Once you have some pages you would like reviewed, you will need to set up your
> git (if you haven't done so already)  -->
> http://book.git-scm.com/2_setup_and_initialization.html
> 
> Then for each new .page you have created type:
> 
> git add <new page name>
> 
> then type:
> 
> git commit -a -m "quadrapasse docs: start of Mallard docs"
> 
> 
> Now you will want to create a .patch file:
> 
> git format-patch HEAD^
> 
> This will create a .patch file in your current directory.  This is the file you
> should attach to this bug.  Once it is attached, someone will review it and
> give you feedback.
> 
> Feel free to talk to members of the documentation team on #docs during your
> progress.  :-)

Thanks Elena!

Created attachment 210791 [details] [review]
first draft patch for changing the old format to Mallard

I am sending you the first draft. I have included some additional information in the documentation.

Review of attachment 210791 [details] [review]:

Hi Elena,
  
  This patch deletes the content and completely alters the contents of gnome-sudoku/help/C/commandline.page.  I don't think you meant to do that :-)

  There are a couple errors on quit.page:

       Unmatched inline element: i

  For each page which you added, you could type "yelp <page name>" and look at the terminal to check for errors.
  
The icon is not showing up on each of the pages, just on the index.page.  Looking at how the other docs do this should help you.

Can you fix these issues and upload the changes in a second patch?

Hi Tiffany, 

Certainly I will fix the issues and upload it in the second patch. By following the example, I thought that we should use the other versions that are already finished in order all manuals to be similar to each other and easier for the users to adapt to them. 
It will not be a problem at all changing it; and I will send it to You as soon as possible. 

Thank You, 
Elena

Maybe that is the reason why I somehow got in touch with the other document, because I was analyzing the way you have done it, and tried to imply the knowledge from the Mallard manual together with your way of working.

Created attachment 210804 [details] [review]
This is the patch with corrections made. I do apologize for the first one though.

Created attachment 211320 [details] [review]
Improving the design of the previous documentation.

Created attachment 211380 [details] [review]
One more change - GNOME image :)

Created attachment 211964 [details] [review]
After the comments from my mentor (Tiffany Apostolski)

(In reply to comment #11)
> Created an attachment (id=211964) [details] [review]
> After the comments from my mentor (Tiffany Antopolski*)

* I am sorry for the mispronunciation. :)

Review of attachment 210804 [details] [review]:

See further notes below.

Review of attachment 211380 [details] [review]:

ok

Review of attachment 211964 [details] [review]:

ok.

Review of attachment 211320 [details] [review]:

okay

Hi Elena,
 
Sorry about the long wait :-(  Okay, I took all your patches and merged them into one and pushed them to the master branch... You can see your commit here:

http://git.gnome.org/browse/gnome-games/commit/?id=f679c7c9a7430b88e2b3365d976d01fc66e168c4

Additionally, I made some small changes (For example, use of the guiseq element, the keyseq element, removed screenshots (wrong theme and English strings) which remained, and used html codes to refer to the arrow keys).  

There was a validation issue too, (which took even me a while to figure out).  The section element strictly requires an id and a title (which became apparent when using the yelp-check validate tool).  This is actually not mentioned on the Mallard tutorial, and was far from obvious.  

You can see my changes here: 
http://git.gnome.org/browse/gnome-games/commit/?id=ee1c7a16162f23823b203bff0f03b7f390d1c341

Now, as you found out and mentioned on irc, the docs should definitely be updated to the 3.4 version you saw on your Ubuntu 12.04 install.  These docs are complete, just need the update, and then the gnome-games team will include them in the next point release.

So at this point, you should just do a fresh clone of the repository, and all your pages will there, with my changes included.  

Thanks for your work!

Hi Tiffany, 

Thank you for the response, and for the changes. 
For the section element, I didn't know it, but it's always good to find out something new !!! :) 
It's great that the help section will be included in the new update! 

Thank you for your help while making the documentation for quadrapassel ! 
Elena

Final updates matching 3.5.5 pushed to master.  

commit: http://git.gnome.org/browse/gnome-games/commit/?id=d70ba5d50218fb23112fd9a265c3a635fbab8bbe

Closing this bug.