[drupal-docs] Where do I start

[Ron Mahon]

If you ever had the job of managing a team of developers and trying to get
them to document what the completed... Your fears would evaporate. 
Ron


InterNet Marketing Resource Center
A Free Super Mart of Articles, Demos, Tutorials everything you need to
Succeed on the net.
www.inmrc.com 


-----Original Message-----
From: Kieran Lal [mailto:kieran at civicspacelabs.org] 
Sent: Thursday, April 28, 2005 4:58 PM
To: drupal-docs at drupal.org
Subject: Re: [drupal-docs] Where do I start

Hi, understood that you were pro module documentation.  I just wasn't clear.

I took a quick look at a random sampling of module overviews.  Let's take an
example:

"The amazon_search module is a drop-in search engine for Amazon.com's book
store. The search returns a minimally formatted list of books, including the
image Amazon.com provides, the list and Amazon.com prices, a purchase link
and each author's name links to an Amazon search for more books by that same
author. The links can all have an configurable Amazon Associate ID embedded.

The module uses Amazon's ECS4 REST interface to search for books, music or
videos and is extensively commented to help in extending the search to more
categories.

Please note this module uses domxml and curl functions, which I have found
is not always enabled. Try running phpinfo() and searching the output for
the domxml and curl; if these are not enabled this module will not work."

So the first paragraph is general and not too technical.  Although, I
suspect that Anisa and Richard could drop a  verbiage hammer on it none the
less.  When we move to the second and third paragraphs though we 
are clearly moving into developer lingo.   In the survey feed back 
there was consistent advice given to the Drupal Docs team that we 
should avoid using technical jargon and abbreviated syntax.   So if an 
end user is browsing these overview pages what are they going to think when
see words like ECS4 REST interface, domxml, curl functions, phpinfo().

It's basically announcing to new users that you aren't technical enough 
to run this application.   Boris and Richard have taught me that I need 
to keep in mind my audience when writing documentation.   The person 
who wrote this assumed that the audience who was going be like them, a
programmer or a very technical person.

What I am assuming Dan is suggesting is that these overviews could be 
much more like marketing features.   Brief end user descriptions of 
what this Drupal application can give to site administrators and 
endusers.   If the technical details are necessary in the overview then 
it should indicate that this is audience.

I think we need to move beyond having developers be exclusively 
responsible for creating and controlling documentation.   Of course, 
there can be a working collaboration, but doc writers need to be able to
have equal say when it comes to all documentation aspects of Drupal.

Cheers,
Kieran