<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
FWIW,<br>
<br>
The audiences I can see in this situation are:<br>
<br>
reader<br>
author<br>
administrator<br>
developer<br>
<br>
The functions by which documentation could be organized correspond to
this:<br>
<br>
reading<br>
authoring<br>
administering<br>
developing<br>
<br>
A refinement would be a basic/advanced matrix:<br>
<br>
reading-basic<br>
reading-advanced<br>
authoring-basic<br>
authoring-advanced<br>
administering-basic<br>
administering-advanced<br>
developing-basic<br>
developing-advanced<br>
<br>
In addition there could be a "getting started" and "roadmap" for each
function<br>
<br>
The documentation divisions would of necessity be somewhat arbitrary,
though the principles for such categorization could and should be
documented. To accomodate such arbitrariness, the documentation could
and should have a glossary and an index. To control the documentation,
it should have the usual format, structure, and best practices
guidelines.<br>
<br>
Finally, documentation implementation (such as search performance) and
management (such as scalability, change management) issues could be
considered.<br>
<br>
The developer section of the documentation would be the hard core
design and implementation stuff, which incidentally could position the
product in terms of a rationale for an OOP implementation in version 3.<br>
<br>
Shouldn't take more than a couple of years<grin><br>
<br>
- Henrik<br>
<pre class="moz-signature" cols="72">Henrik Bechmann
<a class="moz-txt-link-abbreviated" href="http://www.osscommons.ca">www.osscommons.ca</a>
<a class="moz-txt-link-abbreviated" href="http://www.bechmannsoftware.com">www.bechmannsoftware.com</a>
<a class="moz-txt-link-abbreviated" href="http://www.newsreader.ca">www.newsreader.ca</a> (experimental)
Webmaster, <a class="moz-txt-link-abbreviated" href="http://www.dufferinpark.ca">www.dufferinpark.ca</a></pre>
<br>
<br>
<br>
<blockquote cite="mid200508041805393.SM01900@host.pmichaud.com"
type="cite">
<pre wrap="">
Message: 1
Date: Thu, 4 Aug 2005 19:17:18 -0500
From: "Patrick R. Michaud" <a class="moz-txt-link-rfc2396E" href="mailto:pmichaud@pobox.com"><pmichaud@pobox.com></a>
Subject: Re: [pmwiki-users] audiences revisited or revised ???
To: Neil Herber <a class="moz-txt-link-rfc2396E" href="mailto:nospam@eton.ca"><nospam@eton.ca></a>
Cc: pmwiki users <a class="moz-txt-link-rfc2396E" href="mailto:pmwiki-users@pmichaud.com"><pmwiki-users@pmichaud.com></a>
Message-ID: <a class="moz-txt-link-rfc2396E" href="mailto:20050805001718.GL30367@host.pmichaud.com"><20050805001718.GL30367@host.pmichaud.com></a>
Content-Type: text/plain; charset=us-ascii
On Tue, Aug 02, 2005 at 11:35:07PM -0400, Neil Herber wrote:
</pre>
<blockquote type="cite">
<pre wrap="">I have been updating some of the docs and have had second thoughts about
how to refer to audiences in a consistent way that everybody agrees with.
Does the following make sense?
1) A generic term for anyone accessing the wiki is a "user".
2) Users may also be "authors", that is, individuals who add to or edit the
content of the wiki.
3) A generally limited number of users are "admins", individuals who can
control the operation of the wiki in various ways.
</pre>
</blockquote>
<pre wrap=""><!---->
<soapbox>
For some time I've been on a campaign to reduce the use of the
word "users". In reviewing papers, proposals, and design documents
I find that authors too often lazily toss around the generic and often
ambiguous word "user" -- often it ends up being an unbound pronoun.
Better are words that indicate the role of the person being referred to,
such as author, reader, writer, client, customer, supplier, programmer,
developer, teacher, student, vendor, regulator, ...
As an extreme example, I once reviewed a master's thesis that contained
"user" four times in a single sentence, with each use of the word
referring to a different individual.
That said, I know it's a losing battle, and I also know that the
name I gave to this mailing list makes me a bit hypocritical on this
point. :-)
In general I'd prefer to stick with "authors", "admins", and "readers",
and perhaps use "all" or "person" when we're referring to someone
who could be in any of these roles. This isn't to say that we
can never use the word "user" in the docs, but I'd hate to formalize
its usage.
</soapbox>
</pre>
<blockquote type="cite">
<pre wrap="">Rather than ascribing abilities to the users, why not ascribe a level to
the material being documented? This is already done to some degree with
page names like Simple Tables and Advanced Tables.
</pre>
</blockquote>
<pre wrap=""><!---->
This is probably good.
</pre>
<blockquote type="cite">
<pre wrap="">One question that occurs to me: Do we really need a "user" audience? And I
am sure that the answer is yes. Docs for users would include such topics as:
* what can PmWiki do?
* PmWiki philosophy
* WikiWikiWeb
</pre>
</blockquote>
<pre wrap=""><!---->
In this case I'm certain there's an audience that corresponds to the
group you're referring to here, but I'm equally certain that "users"
isn't really the best word to describe that audience. :-) In
this case the audience is more like "people interested in learning
more about PmWiki", which means we could probably identify these
specific documents by their topic ("About PmWiki") as opposed
to the intended audience.
Pm
</pre>
</blockquote>
</body>
</html>