Suggestions for re-documenting Drupal

[Nick]

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?

[Marjorie Roswell]

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.
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.
4.I don't agree with you about the word "documentation" I think it's a great
word.
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.

Those are my thoughts for the moment,

Margie

Post by Nick
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.
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/

[Steven Peck]

Post by Marjorie Roswell
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.

Post by Marjorie Roswell
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?

Post by Marjorie Roswell
Margie

Steven Peck

Post by Marjorie Roswell

Post by Nick
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.

Post by Nick
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.

Post by Nick
I posted an issue that I think really captures what I'd like to suggest.
http://drupal.org/node/236444
So what do people think? If not this, what direction will the Drupal

documentation take in the future?

Post by Nick
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?

Post by Nick
--
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/

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

Post by Marjorie Roswell
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
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. :-(

Post by Marjorie Roswell
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
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.

Post by Marjorie Roswell
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.

Post by Marjorie Roswell
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

Post by Marjorie Roswell
Those are my thoughts for the moment,
Margie
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
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/

[Marjorie Roswell]

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

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

Post by Nick
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.
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/

[Addison Berry]

Post by Marjorie Roswell
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.)

Well the original issue for the points in it, but the conversation has
listed a bit form that so we should probably continue this discussion
here. :-)

Post by Marjorie Roswell
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?)

Just because it is new content doesn't mean you need to use the
dropdown. I didn't say new content entry is a problem, because its not
unless you are creating a new top-level item or trying to move an item
from one place to a very different place. Both of those activites are
pretty rare on d.o which is why I said the dropdown is not an issue
99% of the time and typically the folks that do encounter it are d.o
site admins, not average docs team folks.

New content should be created with the Add child page link. You just
go the page that will be that parent for your new page and click the
Add child page link. That does the placement for you. E.g. if you
wanted to add a new module handbook page in the Event modules section,
just go to http://drupal.org/node/206786 (the Event modules page) and
click the Add child page right there. Easy peasy. You don't even need
to be on the docs team to do that. Everyone with a d.o account can add
child pages wherever, whenever they want.

Post by Marjorie Roswell
How does wikipedia handle spam? Honest question.

I don't know, I'm not that familiar with it other than reading
articles there.

Post by Marjorie Roswell
Margie

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Marjorie Roswell]

I responded (favorably) to Larry's post at:

http://www.garfieldtech.com/drupal-org-wiki

I've since recorded a tiny little (15-second?) screencast to show what I
mean by the search drop-down ajaxy thing (based on civicrm search) that I
mentioned in the last paragraph. Might be a good way to handle the
documentation dropdown piece.
http://screencast.com/t/qvGyH5TxRyt

[Larry Garfield]

Post by Marjorie Roswell
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.
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 started writing a reply to this point, but it ended up a bit long. So I
made it a blog post instead:

http://www.garfieldtech.com/drupal-org-wiki

[Kristof Van Tomme]

I added an issue and a drop task for this last week: more user
friendly interface to select parent page for book pages

http://drupal.org/node/233876
http://drop.cwgordon.com/node/71

Send documentation mailing list submissions to
To subscribe or unsubscribe via the World Wide Web, visit
http://lists.drupal.org/listinfo/documentation
or, via email, send a message with subject or body 'help' to
You can reach the person managing the list at
When replying, please edit your Subject line so it is more specific
than "Re: Contents of documentation digest..."
1. Re: Suggestions for re-documenting Drupal (Addison Berry)
2. Re: Suggestions for re-documenting Drupal (Marjorie Roswell)
----------------------------------------------------------------------
Message: 1
Date: Wed, 19 Mar 2008 21:40:17 -0400
Subject: Re: [documentation] Suggestions for re-documenting Drupal
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes

Post by Marjorie Roswell
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.)

Well the original issue for the points in it, but the conversation has
listed a bit form that so we should probably continue this discussion
here. :-)

Post by Marjorie Roswell
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?)

Just because it is new content doesn't mean you need to use the
dropdown. I didn't say new content entry is a problem, because its not
unless you are creating a new top-level item or trying to move an item
from one place to a very different place. Both of those activites are
pretty rare on d.o which is why I said the dropdown is not an issue
99% of the time and typically the folks that do encounter it are d.o
site admins, not average docs team folks.
New content should be created with the Add child page link. You just
go the page that will be that parent for your new page and click the
Add child page link. That does the placement for you. E.g. if you
wanted to add a new module handbook page in the Event modules section,
just go to http://drupal.org/node/206786 (the Event modules page) and
click the Add child page right there. Easy peasy. You don't even need
to be on the docs team to do that. Everyone with a d.o account can add
child pages wherever, whenever they want.

Post by Marjorie Roswell
How does wikipedia handle spam? Honest question.

I don't know, I'm not that familiar with it other than reading
articles there.

Post by Marjorie Roswell
Margie

------------------------------
Message: 2
Date: Wed, 19 Mar 2008 22:32:43 -0400
Subject: Re: [documentation] Suggestions for re-documenting Drupal
Content-Type: text/plain; charset="iso-8859-1"
http://www.garfieldtech.com/drupal-org-wiki
I've since recorded a tiny little (15-second?) screencast to show what I
mean by the search drop-down ajaxy thing (based on civicrm search) that I
mentioned in the last paragraph. Might be a good way to handle the
documentation dropdown piece.
http://screencast.com/t/qvGyH5TxRyt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20080319/3e497747/attachment-0001.htm
------------------------------
_______________________________________________
documentation mailing list
http://lists.drupal.org/listinfo/documentation
End of documentation Digest, Vol 40, Issue 17
*********************************************

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/