Re: Gnote documentation in Mallard Format

[Phil Bull <philbull gmail com>]

Hi Runa,

Sorry for taking so long to reply to you.

On Mon, 2010-06-07 at 12:38 +0530, Runa Bhattacharjee wrote:
> As part of a recently held Fedora Activity Day[1], I worked on creating a Gnote
> Help documentation in Mallard format. The documentation has been submitted in
> the GNOME Bugzilla[2].
> 
> The original call for volunteers is here:
> 
> http://lists.fedoraproject.org/pipermail/india/2010-May/003439.html
> 
> Please do let me know in case any changes are required to the documentation or
> any other procedural requirements (in addition to the ones mentioned in the link
> above) need to be complied with.

> [1] https://fedoraproject.org/wiki/FAD_Pune_2010
> [2] https://bugzilla.gnome.org/show_bug.cgi?id=620557

I've reviewed the documentation for Gnote that you've written. Overall,
the document looks very good and it would be fine to include it as-is.
I've proposed a few changes/tweaks that you might like to consider
below:

      * Paul Cutler is listed as the author in all of the files (see the
        credit tags in the info sections of each page). If you wrote the
        files, you should change the details from Paul's to yours.
        Alternatively, you can just use the GNOME Doc team's details.
      * In create-note.page, line 30, "<keyseq><key>Alt +
        F12</key></keyseq>" should read
        "<keyseq><key>Alt</key><key>F12</key></keyseq>"
      * Many of the topic descriptions (<desc>) repeat the topic title,
        which isn't very helpful to users. It's best to use the <desc>
        tag to provide alternative wordings or useful information to
        help users identify a topic or answer their question faster. For
        example, a better <desc> for "Create a new note" would be
        something like "Click the Gnote icon and select Create New Note
        to start writing a new note". It answers the user's question
        immediately. A better <desc> for "Create a notebook" might be
        "Notebooks let you organize your notes by collecting them
        together".
      * I'm not convinced that users will understand what is meant by
        the "GNOME Panel". It might be better to use something like "the
        panel at the top of the screen" instead.
      * You don't have to refer to Gnote by its full name all of the
        time. For example, in the Introduction, "It is easy to use"
        would sound better than "Gnote is easy to use". Using the app's
        name repeatedly can make documents sound overly formal or
        repetitive; a good guideline is to only use it if you have to.
      * It might be better to split the Preferences topic into a guide
        with multiple topics (it's OK to have very short topics). This
        will make it easier for users looking for a particular
        preference to find it, and you'll be able to link the more
        important preferences into the Preferences section of the index
        page. (The same goes for the Advanced actions and Common
        problems topics.)

Please let me know if you need any help, or if I didn't explain
something very well.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull