Thanks Reinhard for your remarks.
Timing with the Leo project and community has been pretty curious. Now
I'm writing a "paper" for JOSS (Journal of Open Source Software [1]) and
that implies improving the user documentation. So Reinhard remarks and
the rewriting Leo doc are pretty timely.
[1] http://joss.theoj.org/
Grafoscopio Manual is pretty task oriented, but the idea is to go with
the basics and invite the reader to wide and deep his/her knowledge with
interactive examples after that. Curiously I want to get "lost in
hyperspace" at the beginning of my learning journeys. I want to know how
this particular idea connects with similar ones, how this technology
feels compared with others and after that panoramic view, I go deeper
with my chose technology. So, I'm trying to be task oriented,
introductory and panoramic for this particular document. I don't know if
this is a good approach for Leo. I have never read the full manual,
because I go to the docs to know how to do something and in fact Ville's
Tutorial was the first piece of documentation I connected with: it was
direct, enactive, task oriented.
I'll point to this particular thread in my manual on getting "lost in
hyperspace", coming back to the doc and going deeper after that.
As always, thanks for the food for thought.
Cheers,
Offray
On 15/02/17 02:47, rengel wrote:
On Tuesday, February 14, 2017 at 8:19:46 PM UTC+1, Edward K. Ream wrote:
Here is my new *cardinal rule of documentation*:
*Thou shalt not put thine audience to sleep*
The /first /goal of documentation is to intrigue people so that
they read on.
Documentation is not a novel. I don't want to be 'intrigued' by
documentation. I want to get things done by reading the documention,
as painlessly and fast as possible.
With documentation, I don't read on because it is interesting or
fascinating but because it is useful. /Usefulness/ is the overarching
goal of documentation.
A user normally approaches documentation with a task or problem in
mind, not with the intent to relax.
So the documentation should help to identitify and/or clarify the task
or problem and then direct the user to the right place.
*Use links*:**Links can do a lot of heavy lifting--links to
competitors, examples, and especially, links to "careful"
definitions of terms and more complete explanations. Links should
point to subsidiary pages that /aren't/ part of the main
narrative, not included in TOCs, etc.
Linking is one way to help the user find the right information. But
with linking - especially to external websites, competitors, etc. -
you are entering a dangerous terrain. You are giving up the control of
the presentation, the focus of user is disrupted, and the user might
be lured away from your website altogether. (I'm sure, every Internet
user has experienced this problem. It's known as 'Lost in Hyperspace'
and has been explored extensively by the hypertext community (ie.
http://citeseerx.ist.psu.edu/showciting?cid=563324; for an overview:
http://cs.brown.edu/memex/ACM_HypertextTestbed/papers/20.html).
So /for documentation/, it might be better to restrain one's links to
the own website.
Reinhard
--
You received this message because you are subscribed to the Google
Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to [email protected]
<mailto:[email protected]>.
To post to this group, send email to [email protected]
<mailto:[email protected]>.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.
