[drupal-docs] Where do I start

[Kieran Lal]

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