[documentation] A suggestion to improve drupal.org handbooks

[Charlie Lowe]

I'm just got into this thread yesterday (have been out of town) and did 
not realize then that there is one major problem with including 
additional fields for the individual project pages to provide the type 
of information being discussed: project pages are *not* version 
specific. That 'nixes a lot of the suggestions so far about what kind of 
information to include on those pages.

Now I think we also want to take into consideration what Kieran has said,

"I think what we want to create is a situation where if developers check 
in their modules that the community and the documentation team will show 
up to HELP DEVELOPERS, NOT BURDEN them"

I believe Boris also expressed reservations about making this an 
initiative for the documentation team (excuse me if I'm wrong, Boris).

So the goal here should be to create a situation where good things can 
happen, but not increase the mandatory obligations of anyone. Let's keep 
these principles are our guide.

With that in mind, here are some suggestions.

* If someone is willing to create a patch for the project module that 
links the INSTALL.txt and README.txt files (when they exist) to each 
individual project page, that makes the documentation already available 
more accessible. I say both files, because we should consider whether 
some of the information being discussed in this thread is better off 
separated from installation instructions. The alternative, of course, is 
to pull them into the handbook. But this leaves out all of those modules 
that do not have handbook pages as of yet.

* Perhaps we could have a set of suggested recommendations in the 
handbook for what should be included in those files (note that I say 
"suggested"). But I think these recommendations should be negotiated 
with the development list. The doc list can offer feedback, but what 
information is included in those files should be negotiated with module 
maintainers not be determined by the documentation team. If developers 
make the decision about what to include, they are more likely to 
implement those suggestions and encourage others to do so.

* We obviously do not need another process for how the INSTALL.txt and 
README.txt files get updated. Each project has an issue tracking system. 
I suspect that module maintainers would be more than happy to have any 
improvements to these files be submitted using that method.

* I do not think it's a good idea to suggest or imply that it is the 
role of the doc team to now review and update all INSTALL.txt and 
README.txt files. I think it's fine for anyone wanting to help with a 
particular module's .txt files to work with the module maintainer to 
update them. But I'd be really hesitant to create a situation where 
module maintainers will feel less obligated to provide documentation in 
those files because the doc team is taking over responsibility.

So, comments? Any other suggestions about how we can create the 
situation where good things happen?


Ram Dak wrote:
> Exactly! Having a single document to deal with would bring significant 
> advantages.
> 
> With the new workflow options available (?) in 4.7, we could even make 
> this entire process part of a workflow:
> 
> 1.) Developers fill in the initial documentation in the project fields 
> provided and it goes into install.txt in CVS and the tarballs. To avoid 
> developer resistance, we could make a minimum set of fields required and 
> the rest, not required.
> 
> 2.) This text then goes to people/volunteers on the docs list who 
> install the modules and document its various intricacies. Then, with 
> access to the same form fields as the developers, they add the extra 
> stuff they have documented.
> 
> 3.) Someone (or a set of people if possible, including the developers), 
> reviews the additions and approves them. On approval, the new text gets 
> added to the CVS and module tarballs with the PHP magic you mentioned.
> 
> 4.) Finally, this approved documentation is also automatically added to 
> the drupal.org handbooks
> 
> If this makes sense (not too bureaucratic etc.) and is technically 
> feasible,  I will compile all the suggestions people have made till now 
> for a standard format.
> 
> The drupal.org handbooks can still be the place for more detailed 
> documentation, child pages, tips and tricks stuff etc.
> 
> Ramdak
> 
> 
> 
> */Charlie Lowe <cel4145 at cyberdash.com>/* wrote:
> But this did make me think of one idea. Not sure how hard this is to do,
> but for each module, could we use PHP to pull in the install.txt from
> CVS as a sub-page of the main module page in the "Drupal modules and
> features" handbook? Either that, or have the actual project module page
> automatically pull install.txt from CVS and include it as a link? We
> could then help module developers to provide better install.txt files
> and focus on what information needs to be provided there. Only one
> document to maintain, too.
> --
> Pending work: http://drupal.org/project/issues/documentation /
> List archives: http://lists.drupal.org/pipermail/documentation/
> 
> ------------------------------------------------------------------------
> Yahoo! Photos
> Ring in the New Year with Photo Calendars 
> <http://us.rd.yahoo.com/mail_us/taglines/photos/*http://pa.yahoo.com/*http://us.rd.yahoo.com/mail_us/taglines/photos/evt=38087/*http://pg.photos.yahoo.com/ph//page?.file=calendar_splash.html&.dir=>. 
> Add photos, events, holidays, whatever.
> 
> 
> ------------------------------------------------------------------------
> 
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/