[documentation] Suggestions for re-documenting Drupal

[Addison Berry]

I responded to the issue in the queue and we should probably keep the  
conversation in one place rather than splitting it out between the  
list and queue.

Short responses here:
On Mar 19, 2008, at 7:34 PM, Marjorie Roswell wrote:

> 1. I agree with you about the need for improved documentation.
> 2. Totally agree that the book module (the hierarchy that you refer  
> to) doesn't facilitate good documentation. I may have a different  
> reason for feeling that: It's not the hierarchy that I object to:  
> it's just that it is EXTREMELY time-consuming to use the drop-down  
> to enter an item into the hierarchy. I think it's a huge barrier to  
> adding content.
Many book pages on drupal.org can and should be added as child pages  
to existing content so navigating the dropdown should be a non-issue  
in 99% of cases. That said, yes it is a big usability hurdle and while  
we keep poking sticks at it, no one has come up with a solid plan for  
an awesome UI to handle it. It is particularly nasty on d.o because we  
have such huge books.  :-(
>
> 3. That said, I'm fairly well-resigned that the powers-that-be will  
> almost never cede the book module model for doing this in favor of a  
> wiki. I've seen it discussed on IRC, and the idea of using a wiki  
> was met with such snideness that I basically resigned myself to  
> living with incomplete documentation forevermore. I wasn't a  
> participant in that conversation, but the tone of it seemed to be:  
> this is how we do things, it isn't going to change.
Well wiki seems to mean different things to different people so I'll  
try to address to 2 big ones.
1) Anyone should be able to edit:  This is the most common thing that  
people mean when they say d.o should have a wiki. Well anyone can as  
long as they have a d.o account and simply ask to be on the docs team.  
We did open it up to "free for all/real wiki style" a while back and  
got a lot of vandalism that ended up requiring more resources to clean  
up than benefit gained so we switched it to simply making people ask  
for the right and it is handed out freely.
2) Freelinking structure: I think this is the aspect you are more  
referring to. I dare say responses you have gotten regarding "a wiki"  
are in direct response to the assumption in 1 above, which was a bad  
thing in our experience. The freelinking and having a spread out  
structure rather than a strict hierarchy can have benefits but I'm not  
sure that works as well in a handbook where folks may need to follow  
several pages to get a concept from beginning to end. Perhaps I am  
just not a wiki user so I am not as comfortable with it.

If I am totally off here, please do set me right since I feel that I  
am only guessing at your concerns.
>
> 4.I don't agree with you about the word "documentation" I think it's  
> a great word.

Yep, this is a recent change since many felt it was a better word than  
handbook and better for translation.
>
> 5. Great idea on drupal documentation day. Would be great if you  
> could facilitate it. There was one at DrupalCon, which I was unable  
> to attend, unfortunately.

I'd totally be down with organizing another doc sprint (either  
physical and online or just online.)

- Addi

>
>
> Those are my thoughts for the moment,
>
> Margie
>
> On Wed, Mar 19, 2008 at 4:13 PM, Nick <nickchris at gmail.com> wrote:
> First, a little background: I've been lurking on the Drupal boards  
> and on this mailing list for some time now. I work for a newspaper  
> in the developing world, and in the near term we will be moving a  
> portion of our online media onto Drupal as a test pilot. For some  
> weeks I had been toying with various CMS, and after settling on  
> Drupal, had to climb up the learning curve from a point where I knew  
> very little about PHP and even CSS, to a point where I can now make  
> my own themes and (very basic) modules from scratch. Throughout this  
> I have become fairly familiar with Drupal's documentation,  
> especially as it relates to a self-starters with a deep interest in  
> Drupal but who lack the immediate technical skills to grasp it  
> immediately. Despite my frustrations with the learning curve, I've  
> become yet another starry-eyed Drupal fanatic, and have big plans  
> for contributing, especially in the area of (translating)  
> documentation.
>
> So with that all said: Drupal.org's documentation page needs a lot  
> of reorganization. In fact, right now, it seems like a kind of  
> Achilles heel to certain aspects of its development (theming,  
> translations), despite the fact that developers are flocking to it.
>
> I posted an issue that I think really captures what I'd like to  
> suggest. You can check it out here:
>
> http://drupal.org/node/236444
>
> So what do people think? If not this, what direction will the Drupal  
> documentation take in the future?
>
> Last question: if a group of people raised their hands and said that  
> they loved this idea and would do this, what would the next step be?
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
> --
> 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/20080319/8df283bb/attachment.htm