[drupal-docs] comments

[Charlie Lowe]

Anisa wrote:
> 
> I started reworking Boris's HandbookVersionTwo wiki page to reflect the 
> new handbook and give a place for people who wanted wikiness to have 
> wikiness, but I'm not quite quite done.  I will work on it some more later.

In the new Handbook V2 wiki page, Anisa wrote

"Since the new handbook has been set up, it makes sense to make this 
place a site for the actual development of new handbook pages."

I had thought that the main goal for the new handbook was to provide a 
place to revise the pages separate from the existing handbook. Since 
Djun is reorganizing the existing handbook, if the wiki is used to 
develop those pages, that would eliminate the need for the new handbook, 
wouldn't it?

IMHO, it would probably be better to use drupal.org so that we are 
eating our own dog food and making the process more transparent to the 
rest of the Drupal community. For these very reasons, I think it would 
be better if we develop all of our guidelines and 
documentation--including any restructuring plans--on drupal.org.

Meanwhile, Djun is revising the existing handbook pages rather than in 
V2. Since revision is going on there and I don't personally believe that 
a separate handbook or a wiki is necessary, I'll be jumping in now to 
revise pages there until this group can otherwise come up with a 
coherent, efficient process. Just seem easier to me.
> 
> I do have one thought on targeting documentation...  why not include 
> that /in/ the documentation itself?  Ie, 'This page is aimed at people 
> who want to install Drupal.' 'Target: people who want to install Drupal 
> on IIS.'  etc.  You can also include the underlying assumptions that you 
> are going to make about that user in terms of what you expect them to 
> know; that way you remember when you're writing the documentation, the 
> reader knows, and anyone who wants to write for that page in the future 
> knows.  For example, 'This page assumes you know how to FTP files, 
> create a MySQL database, and edit a php file.'
> 

This might only affect a "cart before the horse" approach: "here's 
documentation I have written; here's who it is targeted for." In other 
words, it can create writer-based text rather than reader-based text 
because the target audience can end up being specified as what the 
documentation does as an end result rather than being centered on what 
users need.

Yet, for most sections,  I imagine that the target audience is not so 
difficult to come up with and the main documentation writers on this 
list can succesfully do so on their own without discussion. Some 
description of the target audience for different sections, such as the 
modules and features section, along with a description of structure, is 
more useful for achieving consistency and helping those newer to Drupal 
and Drupal documentation writing to join in the process.

However, the exception is the About section, which contains a lot of 
marketing materials. Marketing materials are much harder to write, IMHO, 
then the other documentation in the handbook.