[documentation] Documentation session in Vancouver

[Steven Peck]

Also, as I have said before, until Drupal.org gets updated to the new code base and we get all the spiffy revisions behavior stuff worked out, we should hold off on it.   If someone wants to contat drumm and work with him so we can get this in, I think it would be wise to do so sooner thna later.  http://drupal.org/node/38451
 
I don't care if we open it up, but what will be the behavior... right now, if people edit a page, it is and will be in moderation and NO one can see it except site-maintainers.  Drumm has a patch he is/was working on that will set it so that the revision goes into moderation but the orginal page will still be displayed.  I like that idea a lot.  It allows for editing across the board and appeases both sides.  In any case, until we get drupal.org upgraded, I don't think it should be opened up.  After, then sure.
 
In the meantime, will this mean we have more people purusing and adding content?  Frankly, I haven't see a lot of more people doing until lately.  I spent the holiday's in November (at in-laws, bored) looking over and formulating my idea and the month of December bouncing it off people.  My whole idea revolved around making it clear where things go and a progression of reading for folks new and old.
 
I realize that 'Best Practices' are opinions and not fact, but they are the result of repeated config mistakes or missing steps being asked and answered in the forums and as a result, we have a huge reduction in those types of issues being reported.  If people disagree or have an alternative approach to them, then edit/modify/add them.  Otherwise they are all we got and are better then nothing.  I would be THRILLED if people who maintain larger site infrastructures than I do would contribute to them based on their experiance.  But I haven't seen it happening in the last year except the modules help drive.
 
We can keep talking about this, but until people do things, all we do is talk talk talk.....
 
I got FIVE responses to my proposal.  Five.  And they were all positive so I went forward with it and I believe that what I have done is a significant step forward.  I think I explained my vision fairly clearly.  If it can be done without coding, then it goes in Installation and Configuration.  
 
The Customization and theming section is the advanced section and where snippets, code samples, strategies for theme approaches, methodiologies and recipes would go.  This section needs an expanded introduction but essentially, you will need some php, advanced html, SQL background or the willingness to learn.  Now, I am hearing that those types of things don't belong in a handbook as book pages?  This confuses me.  I don't see why not.  The first is basics, the second book (think of these as seperate books which is what they are so actually the link structure isn't as deep as it may at first appear) is about how to deal with and use the flexiblity of Drupal.  How to use Drupal is opinion and goal determined.  Whether to use a page, story or flexinode depends on your criterea and project needs.
 
In any case, I am going to be spending a significant chunk of my time on IRC and in the handbook this weekend moving things around in the next book.  Feel free to start editing/improving content in the Installation and Configuration book now and making it pretty prett and conform to the handbook guidelines.  The install section needs another going over to reduce duplication add the 4.6.5 install.txt and add more verbage and such still.  
 
After that is the developers handbook.  Mainly, there is a lot of duplication there in a few areas that need to be addressed.
 
-sp

________________________________

From: documentation-bounces at drupal.org on behalf of puregin
Sent: Wed 1/11/2006 10:56 PM
To: A list for documentation writers
Subject: Re: [documentation] Documentation session in Vancouver




Well, this should be a lively session!

On 11-Jan-2006, at 10:25 PM, Kieran Lal wrote:

> We need to prioritize opening up the handbook for contributors.

      This implies having the right structure.

      Parts of the documenation are very amenable to this
type of approach:  FAQs, best practices, how-to's,
hacks (snippets).

      Others are not.

      Completely opening up the
documentation  without some kind of
framework for control would be rather
like opening up Drupal CVS for
anonymous committers.

       I'm rather inclined to believe that
there are fewer good technical
writers in the house than good
programmers (though this may
be because they've all run away
screaming)


> I was just reading about the popularity of Digg vs. Slashdot.  Digg 
> is collective ranking where as Slashdot is the personal preferences 
> of a handful of editors.  http://jeremy.zawodny.com/blog/archives/
> 006081.html  It scared me that we are just falling behind by not 
> getting this collaborative nature of contributions.
>
> The documentation handbook is managed by a small subset of the site 
> maintainers.  It's time to drink the cool-aid and open it up, or at 
> the very least make good use of revisions :-)
>
> Cheers,
> Kieran
>
>
--
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/20060112/20900c5b/attachment.htm