<HTML><BODY style="word-wrap: break-word; -khtml-nbsp-mode: space; -khtml-line-break: after-white-space; "><BR><DIV><DIV>On Jan 22, 2006, at 6:25 AM, Ram Dak wrote:</DIV><BR class="Apple-interchange-newline" style="font-size: 2px; "><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; ">Exactly! Having a single document to deal with would bring significant advantages.</SPAN><BR style="font-size: 20px; "></DIV></BLOCKQUOTE><DIV><BR class="khtml-block-placeholder"></DIV>We we have currently implemented a single source documentation effort for the Administration help pages. It's been partially successful. We update pages in the handbook: <A href="http://drupal.org/handbook/modules">http://drupal.org/handbook/modules</A>. We have a script that can turn those pages into patches which update the help inside the modules. It took the documentation team about 5 months to get the scripts written to make this possible, but we did it. It's now kind of broken again.</DIV><DIV><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; ">With the new workflow options available (?) in 4.7, we could even make this entire process part of a workflow:</SPAN><BR style="font-size: 20px; "><SPAN class="Apple-style-span" style="font-size: 20px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 21px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 22px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 23px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 24px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 25px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 26px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 27px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 28px; "></SPAN><SPAN class="Apple-style-span" style="font-size: 29px; "></SPAN> <BR style="font-size: 20px; "><SPAN class="Apple-style-span" style="font-size: 20px; "> 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.</SPAN><BR style="font-size: 20px; "><SPAN class="Apple-style-span" style="font-size: 20px; "></SPAN></DIV></BLOCKQUOTE><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Sure this is very similar to how the administration help pages are written now. We frequently grab the install, readme, or what ever documentation exists. By the way the documentation is often pretty good, just not consistent between modules. We then morph this documentation into the administration help. </DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>I don't think you want to raise the standards for creating a project. For example compare these two lists: <A href="http://drupal.org/project/Modules">http://drupal.org/project/Modules</A> and <A href="http://cvs.drupal.org/viewcvs/drupal/contributions/modules/">http://cvs.drupal.org/viewcvs/drupal/contributions/modules/</A>.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>There is already a lot of resistance to creating projects because it comes with issue queues and requires a higher standard. There is also a LOT of modules in <A href="http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/">http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/</A>. New fields in the project module won't hurt. 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. We need to create a participatory layer around the project modules to demonstrate the untapped value of the Drupal platform.</DIV><BR><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; "> 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.</SPAN><BR style="font-size: 20px; "></DIV></BLOCKQUOTE><DIV><BR class="khtml-block-placeholder"></DIV>Ok, but there are already some 400 modules and only 80 of them are documented. So the real bottleneck is not automation but getting folks on the docs team to step forward and document a module. <BR><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; ">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.</SPAN><BR style="font-size: 20px; "></DIV></BLOCKQUOTE><DIV><BR class="khtml-block-placeholder"></DIV><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; ">4.) Finally, this approved documentation is also automatically added to the drupal.org handbooks</SPAN><BR style="font-size: 20px; "><SPAN class="Apple-style-span" style="font-size: 20px; "></SPAN></DIV></BLOCKQUOTE><DIV><BR class="khtml-block-placeholder"></DIV><DIV>The single sourcing currently comes from <A href="http://drupal.org/modules/handbook">http://drupal.org/modules/handbook</A>. It is going to stay that way. But we can explore how to get text files into the handbook.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><BR><BLOCKQUOTE type="cite"><DIV style="font-size: 30px;" id="RTEContent"><SPAN class="Apple-style-span" style="font-size: 20px; "> 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. </SPAN><BR style="font-size: 20px; "><SPAN class="Apple-style-span" style="font-size: 20px; "></SPAN></DIV></BLOCKQUOTE><BR></DIV><DIV>Or you could write a module handbook page :-) Sorry we have about 10 grand schemes for every contribution that is made right now. That's fantastic that people are so enthused to help. But the pragmatic approach would be to make small incremental improvements to existing efforts and then use the momentum from your contributions to improve the bureaucracy.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Cheers,</DIV><DIV>Kieran</DIV></BODY></HTML>