[documentation] Suggestions for re-documenting Drupal

Thu Mar 20 01:08:22 UTC 2008

apologies for bad descriptive term!

What's the best URL for continuing the conversation? Not quite sure where to
go. (email's easiest for me, if some other location, let me know.)

Honestly, I think the drop-down data entry form is a huge barrier to content
entry, and as you noted, especially for new content entry... but most
modules aren't in the documentation... so lots of room for new entries.
Also, seems many things will require new pages for v6 (or is that not
accurate?)

How does wikipedia handle spam? Honest question.

Margie

On Wed, Mar 19, 2008 at 8:47 PM, Addison Berry <drupal at rocktreesky.com>
wrote:

> 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/
>
>
>
> --
> 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/ebd04c32/attachment-0001.htm 