Re: Gnote documentation in Mallard Format
- From: Paul Cutler <pcutler gnome org>
- To: Phil Bull <philbull gmail com>
- Cc: gnome-doc-list gnome org
- Subject: Re: Gnote documentation in Mallard Format
- Date: Mon, 26 Jul 2010 17:49:17 +0200
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
>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]