[drupal-docs] Admin help longs to be read by skilled Drupal user

[Steven Peck]

RSS and OMPL are what aggregator is.  It is not to technical.  It is an accurate description of what it is.
 
If you don't know what they are, then you should look them up.  If you are going to be a site administrator you need to learn the vocabulary in order to search for information on it.  This is part of your responsibility in maintaining a site that uses powerful features.  Discuising the difficulty, simplifying the explanation are all OK.  Not using the proper wording and vocabulary is wrong.  You are not helping people by talking down to them, you are hindering them and doing the audience a disservice.  
 
For instance, I know quite a bit about how email to works.  Transport layers, transmission, etc.  You don't need to know any of that to setup your mail client however, you still need to know what type of account you have.  POP, IMAP and the associated SMTP information or MAPI account.  Do you need to know the difference? No, do you need to know what type you have to setup your email?  Yes.  To follow the instructions there is a spot for type of email.  It is very relevant to making it work.
 
Do you need to know what a virus is to use email?  No.  Do you need to know what anti-virus is?  No.  To make email work you do not.  However, it is completely irresponsible not to have an awareness of this information.  You put your system, your data and your acquaintences system and data at risk if you do not hafve at least a basic understanding of this.  Being unwilling to learn the basics of a complex and powerful application you are going to use is a problem.  We should not write documentation assuming that our user base in incapable and unwilling to learn the basics of running a CMS based website.  
 
Our users are capable of learning.  If we see a term, then we need to have a glossary or link to wikipedia definitions.  We can then continue to refer to something by it's proper name/term.  Using proper names/terms allows site admins to look up these terms and search the Internet for articles on leveraging these technologies.  If we 'make up' simple names, we continue down the path to obscurity that Drupal already has a reputation for.
 
When I started this I knew nothing about MySQL, RSS, CSS and a boatload of other terms.  Drupal was more challanging to use and setup.  I still managed.  This stuff is making it easier.  It continues to do so.  We should still strive for technical accuracy to accomplish this.
 
An final example, for teachers, in the Western US, WASC is a very important term.  You have a difficulty being a teacher without knowning what that is. :)
 
-sp


________________________________

From: drupal-docs-bounces at drupal.org on behalf of Kieran Lal
Sent: Sat 5/28/2005 7:39 PM
To: drupal-docs at drupal.org
Subject: Re: [drupal-docs] Admin help longs to be read by skilled Drupal user



On May 28, 2005, at 7:13 AM, Anisa wrote:


	Some of it is a little techy...  Is that OK?  (ex. RSS, OPML in aggregator).
	


No it's not OK to be too technical.  There is a place to be too technical and I suggest that it's the handbook, module sub pages.  Admin help, and the first page of the module documentation should be comprehensible by new users.

Could you tell me which modules are too technical and I'll take a look at rewriting them.  Of course if you have the time just go ahead and change them yourself.  We do have revisions available :-)

Thanks,
Kieran



	I long to delete some of these old comments...
	
	Anisa.
	
	Kieran Lal wrote:
	

		Howdy, 203 of you completed the Drupal documentation survey and told  
		us that the number one thing you wanted was module documentation.
		
		The goal of this admin help documentation is:
		1) Provide documentation for Drupal modules.
		2) Improve the usability of the admin help.
		3) Improve the documentation teams ability to work with admin help by  
		single sourcing it from the documentation handbook.
		
		Here is the documentation for Drupal core:http://drupal.org/handbook/ 
		modules
		Here is the documentation for some of Drupal contributions: http:// 
		drupal.org/handbook/modules/contributions
		
		The handbook module pages start with executive summaries that are  
		also admin help.  Pretty clever, don't you think.  The handbooks are  
		currently under development, stay tuned for more improvements.  It  
		would be greatly appreciated if knowledgeable Drupal users could read  
		some of them and report back on where they are wrong.
		
		If you need a site to confirm this documentation, create an account  
		on: http://demo.civicspacelabs.org/home and send me a link to your  
		profile.  I'll make sure you get the access you need to confirm the  
		documentation is accurate.
		
		Thanks for you help,
		Kieran
		
		  

	-- 
	[ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]



-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/ms-tnef
Size: 7825 bytes
Desc: not available
Url : http://drupal3.drupal.org/pipermail/documentation/attachments/20050529/45987e68/attachment.bin