[documentation] help
Drupalancer
drupalancer at gmail.com
Thu Mar 20 13:30:48 UTC 2008
-----Original Message-----
From: documentation-bounces at drupal.org
[mailto:documentation-bounces at drupal.org] On Behalf Of
documentation-request at drupal.org
Sent: Thursday, March 20, 2008 6:38 AM
To: documentation at drupal.org
Subject: documentation Digest, Vol 40, Issue 16
Send documentation mailing list submissions to
documentation at drupal.org
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
documentation-request at drupal.org
You can reach the person managing the list at
documentation-owner at drupal.org
When replying, please edit your Subject line so it is more specific
than "Re: Contents of documentation digest..."
Today's Topics:
1. Re: Suggestions for re-documenting Drupal (Addison Berry)
2. Re: Suggestions for re-documenting Drupal (Larry Garfield)
3. Re: Suggestions for re-documenting Drupal (Marjorie Roswell)
----------------------------------------------------------------------
Message: 1
Date: Wed, 19 Mar 2008 20:47:38 -0400
From: Addison Berry <drupal at rocktreesky.com>
Subject: Re: [documentation] Suggestions for re-documenting Drupal
To: A list for documentation writers <documentation at drupal.org>
Message-ID: <194882CD-1663-43A3-B28B-5F04DD005747 at rocktreesky.com>
Content-Type: text/plain; charset="us-ascii"
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/8df283b
b/attachment-0001.htm
------------------------------
Message: 2
Date: Wed, 19 Mar 2008 20:05:46 -0500
From: Larry Garfield <larry at garfieldtech.com>
Subject: Re: [documentation] Suggestions for re-documenting Drupal
To: A list for documentation writers <documentation at drupal.org>
Message-ID: <200803192005.47083.larry at garfieldtech.com>
Content-Type: text/plain; charset="utf-8"
On Wednesday 19 March 2008, 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.
> 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
--
Larry Garfield AIM: LOLG42
larry at garfieldtech.com ICQ: 6817012
"If nature has made any one thing less susceptible than all others of
exclusive property, it is the action of the thinking power called an idea,
which an individual may exclusively possess as long as he keeps it to
himself; but the moment it is divulged, it forces itself into the possession
of every one, and the receiver cannot dispossess himself of it." -- Thomas
Jefferson
------------------------------
Message: 3
Date: Wed, 19 Mar 2008 21:08:22 -0400
From: "Marjorie Roswell" <mroswell at gmail.com>
Subject: Re: [documentation] Suggestions for re-documenting Drupal
To: "A list for documentation writers" <documentation at drupal.org>
Message-ID:
<aa0037c80803191808h5f74adc9v380a4d79605eb053 at mail.gmail.com>
Content-Type: text/plain; charset="iso-8859-1"
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/ebd04c3
2/attachment.htm
------------------------------
_______________________________________________
documentation mailing list
documentation at drupal.org
http://lists.drupal.org/listinfo/documentation
End of documentation Digest, Vol 40, Issue 16
*********************************************
More information about the documentation
mailing list