[drupal-docs] comments

[Anisa]

Hm.  Well, I don't personally think it's an efficient workflow to do 
everything on the wiki and then transfer it over.  It's not a 
particularly efficient kind of wiki.  I don't make it because I think it 
will be better, but just to provide a place in case someone wants to use it.

The current workflow is... what, precisely?



Charlie Lowe wrote:

>Anisa wrote:
>
>>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.
>  
>

Depends on who is writing them.

I'm pretty fond of the idea, and I believe in its value.  You always 
have the option of rejecting donated documentation or editing it 
yourself.   But I will write some pages so you can see.  :)

Anisa.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050517/2e5341b8/attachment.htm