Re: Review documentation of Solang

[Phil Bull <philbull gmail com>]

Hi Florent,

On Sat, 2010-02-06 at 16:19 +0100, THEVENET Florent wrote:
> Since about two weeks, I write documentation for Solang (a photo
> manager), using Mallard.
> 
> Rishi and I would like to merge our git "doc" branch with master but
> before it would be great if someone could review the documentation I've
> written.
> 
> You can get Solang from http://git.savannah.gnu.org/cgit/solang.git/ 
> then do: git branch doc origin/doc
> and : git checkout doc
> to get the doc branch
> 
> (Solang is hosted on git.gnome.org too but I work on Savannah because I
> don't have a git.gnome.org account)

I've done a quick review of this, using the version of Solang which is
packaged for Ubuntu Jaunty (0.3-0ubuntu1). I understand if this is a bit
outdated.

First of all, nice work! It's looking pretty good as it is. Here's a
list of comments, most of which are pretty minor:

      * "How do I import photos?" - this section isn't very useful at
        the moment. When I start Solang in Ubuntu, Tracker isn't
        running, and Solang doesn't display any photos. The help should
        tell me that I need to start Tracker, or that I should use the
        Photo -> Import From menu.
      * "How do I import photos?" - also says that I don't need to worry
        about importing photos from my camera, because they will already
        be there. Is this true? What happens when you disconnect the
        camera? Are the photos copied automatically?
      * "How do I export photos?" - I think that this section would
        benefit from a more descriptive name, since users might not
        think of "copying photos to a different folder" as "exporting."
      * There are spaces between the end of sentences and punctuation
        marks like "!" and "?". This isn't stylistically consistent with
        the other docs, so the spaces should be removed.
      * "What's a tag?" - The phrase "Tags are keyword[s] or terms you
        can associate with a document" might be confusing, since most
        users are unlikely to think of photos as being a type of
        document. Maybe it's just best to say something like "Tags are
        keywords that you can use to label and organize photos." Using
        an example of a tag is also a good idea.
      * "What's a tag?" - This section should also have a link to the
        other topics on using tags.
      * "How do I use tags?" - I think that this topic should be split
        up into two sections: one on adding/modifying/removing the tags
        of an individual photo, and one on creating/deleting tags.

Here are a few topics that you might consider covering:

      * What does the histogram show?
      * How can I correct problems with my photos?
      * My photos are the wrong way around
      * Shrinking photos down to size
      * Where has the sidebar gone?
      * I want to see more photos on the screen
      * Why does it take so long to import my pictures?
      * What keyboard shortcuts can I use?

Thanks,

Phil

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