[documentation] Proposal for a "Contributing to Drupal" handbook section

[Addison Berry]

Thanks to Mike for spending the time to type up the notes from the  
hours we spent jabbering about this yesterday - not a small task! ;-)  
I'm going to be on the low down for a few more days, catching up from  
being away so I'll fill out some of my other thoughts later this week.

Re: the book thingy here, this is not a new "book", it is a new  
section which will live in a book (not yet created.) There will be a  
new book for all of the drupal.org-specific stuff (I'll let Steven  
Peck speak more to that) and our original idea was that this stuff  
here would simply be one bit of it, but I don't know how the overall  
org for that will go - it is *very* fluid right now.

That said, there is a *ton* to be said on most of these topics. The  
idea is not to just list the mechanics of how to click the right  
buttons or type the right commands, but to explain the nuances of the  
community, give context and give people enough information so that  
they are not scared to attempt something. For example, in brief  
conversations with several people it is clear that the issue queue is  
a terrifying place and taking the time to explain what it is, all of  
the little pieces and how to use it is not necessarily a one page  
document IMO. Same goes for things like documentation and testing/ 
reviewing patches. The contribute code/CVS stuff is in the planning  
stage of becoming a new reorg'd section already and will definitely no  
longer be housed in the Dev book per Steven's plans for a d.o-specific  
book. Sitting down to work on the reorg/rewrite of that section is  
actually what spawned us coming up with and working on the greater  
contributing section stuff.

Basically the idea is to really make a contributing guide that will  
walk a newbie through every single step if they want it (and I find  
more and more people do want that) but let bolder people jump to what  
they need.  I think we still need plenty of playing around with the  
exact organization and naming of things and I don't expect the  
finished product to look like what we have right now. If folks have  
ideas for totally new ways to organize the info we are targeting here,  
please feel free to propose your outline over the next week or so and  
we can really hash it out. Honestly we got burnt out before we really  
nailed down a lot of this stuff, so feel free to keep it rolling and  
get it solid.

- Addi (add1sun)


On Mar 8, 2008, at 12:00 PM, Lee Hunter wrote:

> This sounds like an excellent, however most of what you're  
> describing as top-level subsections seem to be  fairly trivial (i.e.  
> not enough content for a top level subsection) and the one that is  
> really substantial (Contribute Code) would be a better fit for the  
> developer guide.
>
> I would suggest rather than think of this as a whole new "book",  
> that it be done more along the lines of a white paper with no more  
> than a page for each of the subsections. Where there's a more  
> lengthy discussion and a number of procedures (Contribute Code) just  
> provide links to other sections.
>
> Lee H.
>
>
> On Fri, Mar 7, 2008 at 7:00 PM, Mike Booth <mike at michaelfbooth.com>  
> wrote:
>
> We propose that there be a new handbook section, titled "Contributing
> to Drupal", with the following top-level subsections:
>     Get an Account
>     Talk With The Community
>     Use the Issue Queue
>
>     Report a Problem
>     Suggest Features
>
>     Write Documentation
>     Test New Features
>
>     Contribute Themes
>     Contribute Code
>
> (These titles are tentative and may not be quite what we want. Feel
> free to suggest more alternatives and to point out what we missed.)
>
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20080308/1634b3e7/attachment.htm