Re: Review documentation of Solang

[Shaun McCance <shaunm gnome org>]

On Sat, 2010-02-06 at 16:19 +0100, THEVENET Florent wrote:
> Hello all,
> 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'm going to try not to duplicate Phil's comments here,
because he gave you a top-notch review.

"Introduction to Solang" is going to be one of the most
viewed pages.  A curious user who checks the help first
is very likely to click there to get an overview.  You
have maybe five minutes of attention span, and that's
only if you grab their attention right off the bat.

Make it count.  Don't bother them with technical jargon.
("Tracker?  What's that?  Do I care?")  Don't talk about
what it can do; show it happening.  Your goal is for the
user to do stuff and want to do more.  In five minutes.

"How do I import photos?" is a misnomer.  I know I asked
for it, because I opened Solang ad saw nothing.  But this
page doesn't really help me.  What would probably address
my problem best is a troubleshooting page like "My photos
aren't showing up."

Importing photos can also mean grabbing them off your
camera.  I think that's something people still need to
do, even if the photos don't need to be in a special
Solang database or whatever.  Does Solang do this?
Chances are very good your users are going to look
for this.

"Solang uses a powerful yet hard to understand search
function."  Nobody wants to read past that sentence.

There's a lot of "How do I...?"  We're all forging new
territory here, and we haven't yet agreed on guidelines
for topic naming and such.  If you ask someone else, you
might get different recommendations.  But here's my basic
naming convention:

* Topic page titles are second-person command:
  "Search your photos"
  I would not necessarily use a command in other languages.
  The form comes from dropping "How to" from a noun phrase
  like "How to search your photos".  Sentence caps because
  it's a sentence.
* Troubleshooting page titles are a descriptive sentence:
  "I don't see any photos"
  Sentence caps because it's a sentence.
* All other titles are a noun phrase:
  "Using Tags"
  Header caps.

That's *my* style.  You don't have to follow it.

Thanks for all your hard work.  And thanks for hounding
for review requests.  It's easy for us to forget about
who needs reviews.


-- 
Shaun McCance
http://syllogist.net/