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]. 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.
