style: Thread: Addressing Multiple Audiences


[<<] [<] Page 1 of 1 [>] [>>]
Subject: Addressing Multiple Audiences
From: Randy Kramer ####@####.####
Date: 10 Apr 2002 22:48:49 -0000
Message-Id: <3CB4BF79.36A1@fast.net>

A thing that frustrates me is when I'm reading a document focused on a
rank newbie and I know significantly more than that, but I have to
attempt to pick my way through what for me is a lot of extraneous
material to get to the information I need.  VCR manuals seem to be a
typical example -- (seemingly) pages and pages that tell you how to set
the time and date in excruciating detail, but no simple list of the
essential steps for someone who has used another (or this) VCR before. 

(Someone else on the list expressed similar frustration in a recent
post.)

On WikiLearn, I hope to address that issue -- the following is quoted
from

http://twiki.org/cgi-bin/view/Wikilearn/AboutThesePages#Beginner_Reminder_and_BehindTheS:

<quote>
On Wikilearn I expect to have (at least) two and sometimes three pages
on each topic, one named ...Beginner, one named ...Reminder, and
sometimes one named something like ...BehindTheScenes.  

The one named ...Beginner will have all the step-by-step instructions
and details to help a newbie.

The one named ...Reminder will have a list of the necessary steps, with
little or no explanation, useful to someone who has gone through the
Beginner page previously and needs a reminder, or to someone who has
some knowledge of computers but has never used the particular operating
system, program, or function being discussed. 

The WikiLearn pages on ftp may be a reasonable first cut at this
approach -- see these pages: 

http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpBeginner 
http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpReminder
 
In other circumstances, there may be pages covering installation (or
other appropriate topics), like: 

InstallingFtpBeginner 
InstallingFtpReminder 

The pages named ...BehindTheScenes would provide more explanation, so
that, for example, someone could accomplish the same results using their
own procedures.  As an example, if the ...Beginner and ...Reminder pages
deal with something like setting up a network using a GUI tool, the
...BehindTheScenes page might explain what configuration files were
changed by the GUI and why, and thus, you would learn how you might
configure the network using a text editor.  (This approach might also be
followed even if the ...Beginner and ...Reminder pages deal with setting
up the network using a text editor -- the intent is to provide
conceptual rather than rote knowledge.)
</quote>

Maybe something similar is appropriate for a HOWTO as well?

Randy Kramer
Subject: Re: Addressing Multiple Audiences
From: "Tabatha Persad" ####@####.####
Date: 11 Apr 2002 02:40:09 -0000
Message-Id: <00c101c1e102$94cea780$0928a8c0@voodoochild>

Interestingly, the Gnome Style Guide does it in this manner.  You can find
instant links depending on your experience in the Introduction under "Who
Should Read This Book" and in Documentation Fundamentals under "Reaching
Your Audience".  It could use a little streamlining, but you get the idea...

Links for reference:
http://developer.gnome.org/documents/style-guide/who.html
http://developer.gnome.org/documents/style-guide/fundamentals.html

Tabatha

From: "Randy Kramer" ####@####.####
> On WikiLearn, I hope to address that issue -- the following is quoted
> from
>
>
http://twiki.org/cgi-bin/view/Wikilearn/AboutThesePages#Beginner_Reminder_an
d_BehindTheS:
>
> <quote>
> On Wikilearn I expect to have (at least) two and sometimes three pages
> on each topic, one named ...Beginner, one named ...Reminder, and
> sometimes one named something like ...BehindTheScenes.
>
> The one named ...Beginner will have all the step-by-step instructions
> and details to help a newbie.
>
> The one named ...Reminder will have a list of the necessary steps, with
> little or no explanation, useful to someone who has gone through the
> Beginner page previously and needs a reminder, or to someone who has
> some knowledge of computers but has never used the particular operating
> system, program, or function being discussed.
>
> The WikiLearn pages on ftp may be a reasonable first cut at this
> approach -- see these pages:
>
> http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpBeginner
> http://twiki.org/cgi-bin/view/Wikilearn/UsingFtpReminder
>
> In other circumstances, there may be pages covering installation (or
> other appropriate topics), like:
>
> InstallingFtpBeginner
> InstallingFtpReminder
>
> The pages named ...BehindTheScenes would provide more explanation, so
> that, for example, someone could accomplish the same results using their
> own procedures.  As an example, if the ...Beginner and ...Reminder pages
> deal with something like setting up a network using a GUI tool, the
> ...BehindTheScenes page might explain what configuration files were
> changed by the GUI and why, and thus, you would learn how you might
> configure the network using a text editor.  (This approach might also be
> followed even if the ...Beginner and ...Reminder pages deal with setting
> up the network using a text editor -- the intent is to provide
> conceptual rather than rote knowledge.)
> </quote>
>
> Maybe something similar is appropriate for a HOWTO as well?
>
> Randy Kramer
>
> ______________________
> http://lists.tldp.org/
>

Subject: Re: Addressing Multiple Audiences
From: Randy Kramer ####@####.####
Date: 15 Apr 2002 12:22:41 -0000
Message-Id: <3CBAC460.527E@fast.net>

Tabatha,

Good links, thanks!  

Randy Kramer

Tabatha Persad wrote:
> Interestingly, the Gnome Style Guide does it in this manner.  You can find
> instant links depending on your experience in the Introduction under "Who
> Should Read This Book" and in Documentation Fundamentals under "Reaching
> Your Audience".  It could use a little streamlining, but you get the idea...
> 
> Links for reference:
> http://developer.gnome.org/documents/style-guide/who.html
> http://developer.gnome.org/documents/style-guide/fundamentals.html
[<<] [<] Page 1 of 1 [>] [>>]


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.