[pmwiki-users] Re: pmwiki-users Digest, Vol 2, Issue 33

[Henrik Bechmann]

FWIW,

The audiences I can see in this situation are:

reader
author
administrator
developer

The functions by which documentation could be organized correspond to this:

reading
authoring
administering
developing

A refinement would be a basic/advanced matrix:

reading-basic
reading-advanced
authoring-basic
authoring-advanced
administering-basic
administering-advanced
developing-basic
developing-advanced

In addition there could be a "getting started" and "roadmap" for each 
function

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.

Finally, documentation implementation (such as search performance) and 
management (such as scalability, change management) issues could be 
considered.

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.

Shouldn't take more than a couple of years<grin>

- Henrik

>Message: 1
>Date: Thu, 4 Aug 2005 19:17:18 -0500
>From: "Patrick R. Michaud" <pmichaud at pobox.com>
>Subject: Re: [pmwiki-users] audiences revisited or revised ???
>To: Neil Herber <nospam at eton.ca>
>Cc: pmwiki users <pmwiki-users at pmichaud.com>
>Message-ID: <20050805001718.GL30367 at host.pmichaud.com>
>Content-Type: text/plain; charset=us-ascii
>
>On Tue, Aug 02, 2005 at 11:35:07PM -0400, Neil Herber wrote:
>  
>
>>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.
>>    
>>
>
><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>
>
>  
>
>>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.
>>    
>>
>
>This is probably good.
>
>  
>
>>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
>>    
>>
>
>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
>
>
>
>  
>