[documentation] Suggestions for re-documenting Drupal

[Steven Peck]

On Wed, Mar 19, 2008 at 4:34 PM, Marjorie Roswell <mroswell at gmail.com> 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.

Drupal 6 book module has improvements in this regards.  We are waiting
on several project module related things before drupal.org can move to
Drupal 6.

>  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.

I am sorry, but if you are going to use words like snide, then you
really need to define what you specifically mean by wiki.  Drupal
documentation is already very much like a wiki with the exception that
we use HTML standard as the markup language instead of one of the many
wiki syntaxes which would be a barrier.

As to incomplete?  Can you not add a child page?

> Margie

Steven Peck


> 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/
>