Re: Gnote documentation in Mallard Format

[Runa Bhattacharjee <runa misc gmail com>]

Hello Phil & Paul,

I'm sorry for the late reply. I was traveling for a while and finally got down to
checking all the pending mail. Thanks for all the suggestions. I'll check up on
these and return sometime this week with an update.

Thanks again

regards
Runa

(Apologies for the top-posting)

Paul Cutler wrote:
> 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

--
blog: http://arrbee.wordpress.com
irc: arrbee or runa_b on Freenode
http://fedoraproject.org/wiki/User:Runab