GNOME Bugzilla – Bug 665832
gnibbles: Convert documentation to Mallard format
Last modified: 2013-04-26 13:25:56 UTC
Convert documentation to Mallard format
Working on this. Will upload a patch soon. <info> elements are to be added to all pages.
Created attachment 231385 [details] [review] Drafts for six pages
Review of attachment 231385 [details] [review]: change-controls.page reviewed, please apply the general comments to the other pages. ::: help/C/change-controls.page @@ +11,3 @@ + <email>safincrazy@gmail.com</email> + </credit> + </info> You're missing a description (<desc>), I also prefer to see revision tag above the include and it's nice if you leave blank lines between <link>, <revision>, <include>, <credit> and <desc>. Indent <info> by two spaces, not four and everything inside by four. @@ +13,3 @@ + </info> + + Remove one of these two blank lines. @@ +17,3 @@ + +<p>The <link xref="movement">default controls</link> can be changed in GNOME +Nibbles to suit a player's preference, or for <link "to suit *your* preference". <app>Nibbles</app> @@ +19,3 @@ +Nibbles to suit a player's preference, or for <link +xref="multi-player">multi-player</link> games, when having more than one set of +controls becomes necessary. The <link xref="movement">default controls</link> You have already linked to "movement", once is enough. @@ +20,3 @@ +xref="multi-player">multi-player</link> games, when having more than one set of +controls becomes necessary. The <link xref="movement">default controls</link> +can be changed in the following manner:</p> "To change the default controls:" @@ +24,3 @@ +<list> + <item> + <p>Select <guiseq><gui style="menu">Settings</gui><gui Break line between <gui> tags, not in the middle of one. @@ +28,3 @@ + </item> + <item> + <p>Click any of the <gui style="button">Worm n</gui> tabs, where n is any Tab is not a button. Having that sort of variable can be confusing to users can you reword it? @@ +32,3 @@ + </item> + <item> + <p>In the <gui style="group">Keyboard Controls</gui> box, double click on Technically, one selects the line, then clicks once on the control, not double clicks. @@ +36,3 @@ + use instead of the default key. For instance, to use <key>A</key> to + <gui>Move Left</gui>, double click on <gui>Left</gui> and press + <key>A</key> on your keyboard.</p> Add a note that clicking the item again will cancel the process.
Created attachment 231626 [details] [review] Drafts for six pages 0.2
Review of attachment 231626 [details] [review]: While you do not have to change your indenting style, it would be more consistent with other GNOME applications if you indented <title>, <p> and <list> by two spaces, and all other child tags in a corresponding manner. The game is called 'Nibbles' in GNOME 3, so use 'Nibbles' instead of 'GNOME Nibbles' and make sure to use <app> tags around 'Nibbles'. I have only reviewed change-controls, fake-bonus and general-preferences pages, please update the reset with the general comments about these two. ::: help/C/change-controls.page @@ +15,3 @@ + </credit> + + <desc>Customize controls.</desc> Elaborate, this is supposed to be a more detailed description of the title. @@ +18,3 @@ + </info> + +<title>Changing the default keys</title> Use active tone (the verb 'change') instead of passive tone (the adjective 'changing') because this page is a task; in other words, the page is instructions on how to achieve a goal. The UI refers to the setting as (keyboard) controls, so it is better to use the word 'controls' instead of 'keys' in the title, and 'keys' in the description (which is usually a more elaborate re-wording of the title). @@ +20,3 @@ +<title>Changing the default keys</title> + +<p>The <link xref="movement">default controls</link> can be changed in GNOME Use the link only around 'controls' because that is what you are linking to; this is the page about 'default controls'. @@ +21,3 @@ + +<p>The <link xref="movement">default controls</link> can be changed in GNOME +Nibbles to suit your preference, or for <link Nibbles is the name of the application, so use <app> tags around it. Break the line before the start of the <link> tag as it's not nice to have it spilling over. @@ +27,3 @@ +<list> + <item> + <p>Select <guiseq><gui style="menu">Settings</gui><gui Break between the <gui> tags. @@ +32,3 @@ + <item> + <p>Click any of the <gui>Worm n</gui> tabs, where n is any + number between 1 and the total number of players.</p> Although that you say is clear, I feel that using 'n' is too technical for the average user. Can you reword so that you explain what you are trying to say in more detail? Try something *like* 'Select the tab for the player whose controls you want to edit.' @@ +35,3 @@ + </item> + <item> + <p>In the <gui style="group">Keyboard Controls</gui> box, select the line 'List', not 'box'. It is technically a tree view/list model, feel free to check on the channel or docs list what the correct 'user friendly' word for this is! @@ +36,3 @@ + <item> + <p>In the <gui style="group">Keyboard Controls</gui> box, select the line + and click on the control, then, on your keyboard, press the key that you'd Say what happens when one clicks on the control. Do not use contractions. @@ +37,3 @@ + <p>In the <gui style="group">Keyboard Controls</gui> box, select the line + and click on the control, then, on your keyboard, press the key that you'd + like to use instead of the default key. For instance, to use <key>A</key> 'Want' or 'wish' is nicer than 'like'. Use 'for example' when you give an example, and only use 'for instance' when you talk about a specific instance. @@ +38,3 @@ + and click on the control, then, on your keyboard, press the key that you'd + like to use instead of the default key. For instance, to use <key>A</key> + to <gui>Move Left</gui>, double click on <gui>Left</gui> and press It is a single click, not a double click. The first click focuses, the second click triggers; if the line is already focused, a double click will trigger it twice instead of once. @@ +41,3 @@ + <key>A</key> on your keyboard.</p> + <note style="tip"> + <p>Clicking the control item again, will cancel the change process.</p> A bit less technical here please, what about 'Click New Accelerator… again to keep the old setting.'. @@ +47,3 @@ + <p>Repeat the above step to change the other default keys and click the + next <gui>Worm</gui> tab to change the default controls for + that <gui>Worm</gui>.</p> This needs to be worded better and to correspond to the updated earlier mention of the tabs. ::: help/C/fake-bonus.page @@ +15,3 @@ + </credit> + + <desc>Use fake bonuses in your regular game.</desc> What's a fake bonus? Between the title and the description, I cannot figure it out, so one or the other needs to be a bit more detailed :) @@ +21,3 @@ +<p>You can make GNOME Nibbles more deceptive by enabling fake bonuses. Fake +bonuses look like regular bonus shapes but do not give you any points when +Nibbles swallows them. They merely cause a reversal in the movement of your 'Worm', not 'nibbles'. The reversal is absolute, so do not use 'merely'. It is generally not a help-friendly word @@ +24,3 @@ +worm.</p> + +<!--to add photos Nibbles before and after it has swallowed a fake bonus--> How will a photo demonstrate movement? Maybe a short screen cast will make more sense. @@ +26,3 @@ +<!--to add photos Nibbles before and after it has swallowed a fake bonus--> + +<p>You can enable fake bonuses in the following manner:</p> Be more affirmative. Use 'enable by', 'to enable,' or other more affirmative wordings for this sentence. @@ +40,3 @@ + <p>Click <gui>Close</gui>.</p> + </item> +</list> What happens if the preferences are edited half way through a game? ::: help/C/general-preferences.page @@ +18,3 @@ + </info> + +<title>Changing general preferences</title> 'Change', not 'changing'. @@ +26,3 @@ + <title>Speed</title> + + <p>There are four available speeds on GNOME Nibbles. These are, in '<app>Nibbles</app>', not 'GNOME Nibbles'. @@ +51,3 @@ + +<section id="colours"> + <title>Changing worm colors</title> 'Change', not 'changing'. @@ +82,3 @@ + <gui>Worm</gui> tabs to change their colors. On your left hand side you will + see <gui style="group">Worm color</gui>. Pick a color out of the available + colors in the drop-down menu to change the worm's appearance.</p> '…the appearance of the worm'
Review of attachment 231626 [details] [review]: Reviewed the remaining pages. ::: help/C/index.page @@ +17,3 @@ + +<!--To include info elements and other manadatory sub elements--> +<title>GNOME Nibbles</title> 'Nibbles', not 'GNOME Nibbles'. @@ +19,3 @@ +<title>GNOME Nibbles</title> + +<p>GNOME Nibbles is based on the popular Snake games, with a worm for a '<app>Nibbles</app>', not 'GNOME Nibbles'. @@ +23,3 @@ +desserts. You can score points by swallowing a number of precious objects and +lose points for coming into contact with marked boundaries, maze edges and +other worms present on the screen.</p> The paragraph needs to be reworded: it does not sound particularly user friendly right now. It's probably a good idea to have a look at what other game help pages say if you need inspiration. @@ +30,3 @@ + + <section id="preferences" style="2column"> + <title>Editing preferences</title> This section would be better called just 'Preferences' because some of the sub pages are likely to explain what the settings are, not only explain how to edit them. ::: help/C/movement.page @@ +21,3 @@ + +<p>All worm movements happen with repect to you, unless <link +xref="#relative-movement">relative movement</link> is enabled.</p> This is not worded nicely, try to simplify and elaborate. @@ +36,3 @@ + </item> + <item> + <p><key>Left</key> to move the worm leftwards.</p> Just 'left'. @@ +39,3 @@ + </item> + <item> + <p><key>Right</key> to move the worm rightwards.</p> Just 'right'. @@ +43,3 @@ + </list> +<!--Should I change the link to customise keys to make it a note?--> + <p>You can customize keys <link xref="change-controls">here</link>.</p> Do not use '<link>here</link>', it not nice and also poor style to do so. Something more like 'You can <link>change the default movement keys</link> in the <gui>Preferences</gui>.' would be better. @@ +60,3 @@ + case.</p> + + <p>To enable relative-movement:</p> 'Relative movement' should not be hyphenated. ::: help/C/multi-player.page @@ +15,3 @@ + </credit> + + <desc>Playing GNOME Nibbles with additional players.</desc> '<app>Nibbles</app>', not 'GNOME Nibbles'. @@ +22,3 @@ +a single-player environment, players can additionally control Worms 2-6 in a +multi-player environment. A two-player game allows the players to control Worms +1-2, a three-player game Worms 1-3 and so on.</p> 'Environment' is not a user-friendly term, use 'game' instead. 'Worm 1'/'Worm' should either be in <gui> tags or lower case and with the number written out: chose between '<gui>Worm 1</gui>' and 'first worm'/'worm one'. @@ +27,3 @@ + <title>Choosing the number of players</title> + + <p>GNOME Nibbles can be played by up to 6 players. To set the number of '<app>Nibbles</app>', not 'GNOME Nibbles'. 'Six', not '6'. @@ +31,3 @@ + style="menuitem">Preferences</gui></guiseq>. On your right side, set the <gui + style="input">Number of human players</gui> to the required number, a maximum + of 6. You can do this by using the <gui style="button">+</gui> or<gui Add a space between 'or <gui>', break like before <gui>, not half way through the tag. @@ +33,3 @@ + of 6. You can do this by using the <gui style="button">+</gui> or<gui + style="button">-</gui> buttons, or by entering the number of players from the + keyboard, in the space provided.</p> Remove comma. @@ +39,3 @@ + do so, just set the <gui style="input">Number of human players</gui> to 0 + and set the <gui style="input">Number of AI players</gui> to any number + between 1 and 6.</p> Reword. 'You can watch a <gui>Nibbles</gui> game without participating…'. Do not use 'just'. '…any number between one and six.' @@ +50,3 @@ + game's <link xref="movement#default-controls">default controls</link>, for + multi-player games. You can learn to change the default controls <link + xref="change-controls">here</link>.</p> Do not use '<link>here</link>' style links. For example, use '<note><p>You can <link xref="change-controls">change</link> the movement keys if you do not want to use the <link xref="movement#default-controls">default controls</link>.</p></note>' instead of a new section. Do not use the possessive form when talking about inanimate objects. For example, 'game's default controls' should be 'the default controls in/of the game' or just 'the default controls'. ::: help/Makefile.am @@ +10,2 @@ HELP_FILES = \ + change-controls.page\ Leave a space or a tab between the page and the back slash.
Created attachment 231817 [details] [review] New drafts. Thank you for the detailed review Kat, as always. :)
Created attachment 232229 [details] [review] New drafts I have had a few problems while making this patch. Firstly, I am not able to include any images which are present in data/pix. Since the documents are present in /help/C, the relative path for any file in data/pix is ../../data/pix/<filename>, but when I use this path in a link, I am not able to display the required images. Why is this? I checked the permissions for data/pix and read permission is allowed for the user. I still have a hunch that it's something to do with permissions but I don't know what to do. For now, temporarily, I have copied the files that I want from data/pix to help/C/figures. This is using up space. Secondly, I want some screenshots for a few pages, typically to explain the idea of fake-bonuses. However my game screen hangs when I press the PrtScrn button. :( There are other screenshots in the help/C/figures directory so I am not sure if this problem is unique to me. I'd be really grateful if someone clarified on the above.
As far as I know, all images for documentation reside inside the ../help/C/figures directory. Don't symlink or insert links to images outside this directory. Place all your images in the "figures" directory only. Also make sure you `git add` them. Instead of PrntScreen button, try launching `gnome-screenshot -d x` , where x is number of seconds. For example `gnome-screenshot -d 5` runs GNOME Screenshot tool after 5 seconds. Use Alt + F2 to bring up the run command dialog and enter the above command there, automatically gnome-screenshot will take screenshot after 5 seconds of launch. In case your are in full screen you can introduce more delay, until you can run your game and bring it to the required screenshot state. Hope this helps! :-)
Created attachment 235199 [details] [review] New drafts with screenshots Thank you Sindhu! That helped. Screenshots have been added.
Review of attachment 235199 [details] [review]: ::: help/C/basics.page @@ +15,3 @@ + </credit> + + <desc>Start, pause, resume and quit a game in <app>Nibbles</app>.</desc> …a game of… ::: help/C/change-controls.page @@ +15,3 @@ + </credit> + + <desc>Change the default controls to keys of your choice</desc> Try to make the description sound different from the title. For example, 'Edit the control keys' or 'Set custom control keys'. You are missing a full stop at the end of the description. @@ +21,3 @@ + + <p>The default <link xref="movement">controls</link> can be changed in + <app>Nibbles</app> to suit your preference, or for No comma necessary. @@ +25,3 @@ + more than one set of controls becomes necessary. + To change the default controls:</p> + <list> <steps>, not <list> @@ +34,3 @@ + change.</p> + <note style="info"> + <p>Player 1 controls <gui>Worm 1</gui>, player 2 controls <gui>Worm 2</gui>, player 3 controls <gui>Worm 3</gui> Reflow. @@ +40,3 @@ + <item> + <p>In the <gui style="group">Keyboard Controls</gui> list, select the + line and click on the control. This highlights the line and the words …select the line *then* click… @@ +46,3 @@ + <gui>Left</gui> control line and click it, then, Press <key>A</key> on + your keyboard when you see <gui>New accelerator…</gui> on the + line.</p> This should be at least two steps. @@ +49,3 @@ + <note style="tip"> + <p>Click <gui>New accelerator…</gui> again to keep the old + setting.</p> Does 'Esc' also work? Is there any way to reset it to defaults? ::: help/C/fake-bonus.page @@ +16,3 @@ + + <desc>Use fake bonuses in a <app>Nibbles</app> game to make it more + deceptive and challenging.</desc> 'Deceptive' is not the right word here, just use 'challenging' on its own. ::: help/C/index.page @@ +17,3 @@ + + <title><app>Nibbles</app></title> + <p><app>Nibbles</app> is a Snake game from GNOME. The aim of the game is to "<gui>Snake</gui> game *for* GNOME." @@ +18,3 @@ + <title><app>Nibbles</app></title> + <p><app>Nibbles</app> is a Snake game from GNOME. The aim of the game is to + swallow as many objects as you can while taking care to avoid maze edges and "while avoiding maze walls and" ::: help/C/movement.page @@ +20,3 @@ + <title>Controlling worm movement</title> + +<section id="default-controls"> You don't need a section and a second title for the first part, but leave it in for the second half. ::: help/C/multi-player.page @@ +19,3 @@ + + <title>Multi-player games</title> + <p><app>Nibbles</app> can involve upto six players. While a player controls 'up to' @@ +36,3 @@ + <gui style="button">+</gui> or <gui style="button">-</gui> buttons or + by entering the number of players from the keyboard in the space + provided.</p> Use a <steps> list.
Created attachment 236727 [details] [review] New pages added, and a few changes made Thank you Kat! :) All suggested changes have been made along with some new ones and a few new files have been included. 1)I split the controls page(Which was initially titled movement) into two pages : One listing out the controls and the other explaining relative movement better. 2)A new page has been added to explain scoring. 3)Added enabling sounds/play levels in random order to preferences.page TO DO : Section on contribution to GNOME.
Hi Aruna, sorry for not reviewing this yet! I will review it soon: it generally looks almost ready for merging and I will aim to have it merged by Sunday night as there is a release on Monday. Thanks for all the hard work that you've put into this!
Good going, Aruna!
Created attachment 237545 [details] [review] Get-involved section added Thank you Kat! I missed you on the irc today. I have added more pages by creating a Get Involved Section. I copied pages from Gnome-Sudoku for this from the same section. I hope this is okay. Thanks Sindhu! :D
Review of attachment 237545 [details] [review]: Please update the legal.xml file so that the content is as follows (provided that you agree to license the help under CC-by-SA, which is the documentation team's preferred license): <license xmlns="http://projectmallard.org/1.0/" href="http://creativecommons.org/licenses/by-sa/3.0/"> <p>This work is licensed under a <link href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</link>.</p> </license> This should also fix the remaining validation errors. I generally prefer not to see pages like bug-filing, develop, documentation (which would be better as user-help) and review, but if you want to leave them in, please update the info tags and add the pages to Makefile.am. Also, update the content of these pages to talk about Nibbles instead of GNOME Games as the games have been split up now. If there are any old images that you are not using, delete them and remove them from the Makefile.am. If any of those are screenshots showing the old theme, update them with screenshots that show the new theme. You need to update the pkgversion in the revision tag to 3.7.91 or 3.8 and the status from 'draft' to 'review'.
Created attachment 238152 [details] [review] New drafts Removed pages in get involved section. Made other changes. Hope it's okay!
Review of attachment 238152 [details] [review]: Please use the Adwaita theme when taking screenshots, not Ambiance. Make sure to use the take screenshot application so that you can select to have the screenshot taken only of the current window and without the mouse pointer, or use the appropriate keyboard shortcut that would give you the same result. I am also not convinced that the fake bonus screenshots are showing what you want to show. I have pushed some changes to a user-help branch on top of your patch. 'git checkout user-help' to change to that branch when in your Nibbles directory, fix the screenshot issue (or let me know if you cannot get an Adwaita themed screenshot at the moment) and attach another patch with that fix. If you want to try something more technical, the Makefile needs to be included in the Makefile that is in the srcdir/. Once that is done, you can try building the help to see if there are any errors.
Exams on Monday and Tuesday. Will update the patch by Tuesday evening IST. Thanks Kat!
Created attachment 238905 [details] [review] Changes after review Added new screenshots to rel-movement.page Made some minor corrections to multi-player.page Removed screenshots and commented sections from fake-bonus.page Updated Makefile.am and the figures directory
Review of attachment 238905 [details] [review]: (In reply to comment #20) > Created an attachment (id=238905) [details] [review] > Changes after review You still need to update the other screenshots with Adwaita themed ones :) ::: help/C/controls-change.page @@ +63,3 @@ </item> </steps> + Remove whitespace. ::: help/Makefile.am @@ -14,3 @@ figures/after-rel.png \ - figures/before-fake.png \ - figures/after-fake.png \ Delete these files.
Created attachment 239473 [details] [review] More changes Submitting the patch, for changes made after the previous review.
Comment on attachment 239473 [details] [review] More changes Patch is fine. I've pushed it to the user-help branch on git and will merge to master after the release.
Aruna, I have verified that nibbles help builds. Can you merge the help to master? The instructions in the git book (rebase first, merge second) correspond to that what I usually do. Just make sure that the history is linear before pushing! Ask me on IRC if you need help.
Help has been merged to master. Commit IDs of relevant commits: https://git.gnome.org/browse/gnome-nibbles/commit/?id=d09948c79c795c7394a9559e37930fbcc5313972 https://git.gnome.org/browse/gnome-nibbles/commit/?id=89711e9b6ff45db57ea84683454afd807543306a https://git.gnome.org/browse/gnome-nibbles/commit/?id=7cb01f7b45d9ed5ec51356bba70f495c071f74ec https://git.gnome.org/browse/gnome-nibbles/commit/?id=53e71ffabef377b6e5fe09873ed85f97ad7d6fea Can this bug be closed? :)