[drupal-docs] comments

[Anisa]

Okinawa was sunny and I have tan lines in places that pretty much never 
see the light of day and will hence never be discovered.  What a waste.

I have caught up on all the wonderful discussion about documentation.  
It was interesting.  Technical, but interesting.

This is a somewhat random post, but I thought it would be better to make 
one slightly long post than six little stupid posts.  :)

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.

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.'

I swear someone was working on descriptions for each module (not the 
admin help thing), and I want to say it was Dan, but I can't find the 
message.  Can someone point me to where this is going on?  I think there 
was a wiki page on it.

There's this little notation: 'for {bloggerapi|drupal|ping}.module' on 
the requirements page (http://drupal.org/node/22808).  What do the 
usability experts think about it?  This is not a comment on the page 
itself, since I know it's just a placeholder, but I wonder if this kind 
of notation should be kept out of the documentation.  I know what it 
means, if I think for a moment.  I do think there are invariably nicer 
ways to say the same thing, whatever the situation.  A resolution to 
this question should involve a little line added to the style guide.

We may also want to take a moment and add the 'this is a work in 
progress' line to all the pages in v2; I assume this is getting indexed 
by search.  Alternatively, a block saying the same thing may save a 
little effort, and can be more easily removed.

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