Making handbook editable by all (was Re: [documentation] the documentation site...<snip>)

nathandigriz tesla.nicoli at gmail.com
Thu Jan 12 09:22:02 UTC 2006


Dries Buytaert wrote:

>
> On 12 Jan 2006, at 07:31, Boris Mann wrote:
>
>>>> Only creates are allowed, not edits, as per statement above.
>>>
>>>
>>> This could easily be changed if someone would submit a patch for  
>>> the book module which implements the "edit all book pages" access  
>>> control such as what I included in the wikipage.module I put up on  
>>> my site. If I could figure out how to do it, it must be simple to  
>>> do :)
>>
>>
>> I keep feeling like I'm missing something...doesn't "maintain  books" 
>> give this permission?!
>
>
> I'm willing to do the experiment, but I'm not confident it will work.
>
> Would it be a good idea to allow everyone to commit changes to Drupal  
> core?  I think not.  It takes a small group of people with a good  
> overview to coordinate the many changes, to maintain consistency, to  
> maintain integrity, etc.
>
> I think writing Drupal documentation is more like writing code than  
> writing an encyclopedia with stand-alone articles.  Wikipedia has  
> little or no structure, whereas the Drupal handbook is very  
> structured (much like code is).  People don't read Wikipedia from  
> beginning to end, however, people do read the Drupal handbook from  
> beginning to end.  Thus, you don't need to understand the entire  
> Wikipedia website before you can contribute an article, however, you  
> should have a pretty decent overview of the Drupal handbook, before  
> you should be able to add a new page.  Otherwise, the handbook will  
> grow unwieldy: information will be duplicated, information will be in  
> the wrong place, writing style will differ, people will use  
> terminology before it has been explained properly, the level of  
> detail will be unbalanced, etc.  And that's pretty annoying when you  
> read something from beginning to end.
>
> The alternative is to make the handbook more Wiki-like, and to do  
> away with the impression that you can read it from beginning to end.   
> If it looks like a duck, it quacks like a duck.  So if it looks like  
> a Wiki people will use it more like a Wiki; both when reading the  
> handbook and while contributing to it.  If you call it a book, people  
> will expect it to be a book.
>
> -- 
> Dries Buytaert  ::  http://www.buytaert.net/
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
I think that there are major differences. Those that want to write 
documentation and are interested in it are fewer and as a result the 
need for control will be lessened. Though on the surface they may seem 
similar the collaboration of code and writing collaboration are 
seperate. In technical writing there are many different ways of 
expressing a truth but in the end the truth remains. Code on the other 
hand is much more fluid and the end result sometimes changes. Then there 
is the fact that a typo will not cause a catastrophic failure in reading 
whereas a typo in code may have results that are catastrophic. An 
emxalpe is tihs snetnece... which remains readable and understandable 
even though it is not really english.


More information about the documentation mailing list