Re: Gnote documentation in Mallard Format

[Paul Cutler <pcutler gnome org>]

Hi,

I haven't reviewed the Gnote documentation, but I did finalize the new
Tomboy documentation in Mallard and it was committed to master in Tomboy
a month ago.

The Tomboy documentation was reviewed by Shaun and is licensed under a
CC-SA 3.0 license so there may be some docs that you could re-use.  (If
I am listed as the author in Gnote because Gnote may have re-used the
old Tomboy docs written in Docbook, I was one of 3 or 4 authors - those
docs were licensed under the GFDL and if it re-uses my code, I should
still have attribution but you should also add yourself.  If it's using
my new Tomboy docs - I don't know and don't have time to check on the
hotel wi-fi right now - attribution is also required in the CC-SA 3.0
license too).

Paul

On Mon, 2010-07-26 at 13:10 +0100, Phil Bull wrote:
> 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
>