Nabble - Drupal - Doc

Re: Handbook Page Added Re: "Users" When Installing a Drupal Site

2009-12-15T19:11:30Z

Peter and All,

Here is a link to the video re: installing Drupal at the command line for beginners.. Sorry about that last link.

http://content2zero.com/setting-drupal-site-command-beginners

Pleased to share it.

Shai

On Tue, Dec 15, 2009 at 9:35 PM, Peter Dowling <pwdowling@...> wrote:

Hmm,

Actually Shai, that link doesn't work (the blip.tv).

- Peter

On Tue, 2009-12-15 at 13:08 -0500, Shai Gluskin wrote:

> Yesterday, I created a screencast which is a beginners guide to
> installing Drupal at the command line, I noticed 4 different kinds of
> "users" or "user accounts" that needed mentioning: the computer user,
> the database user, Drupal's user/1 and all other Drupal users.
>
>
> So I wrote a handbook page background piece, aimed at beginners, to
> distinguish clearly between these different "users."
>
>
> Here is the handbook page: http://drupal.org/node/660468.
>
>
> Feedback is welcomed.
>
>
> Oh, if you want to see the screencast, go
> to: http://blip.tv/dashboard/episode/2994420
> (It's long, 30 min... I should really separate out the Drupal install
> from the Drush install. But I was having fun with Screencast, which
> makes it really easy to zoom in on the part of the page you are
> emphasizing so that it is readable, even on a 640 x 480 vid.)
>
>
> Shai

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

Re: Handbook Page Added Re: "Users" When Installing a Drupal Site

2009-12-15T18:35:54Z

Hmm,

Actually Shai, that link doesn't work (the blip.tv).

- Peter

On Tue, 2009-12-15 at 13:08 -0500, Shai Gluskin wrote:

> Yesterday, I created a screencast which is a beginners guide to
> installing Drupal at the command line, I noticed 4 different kinds of
> "users" or "user accounts" that needed mentioning: the computer user,
> the database user, Drupal's user/1 and all other Drupal users.
>
>
> So I wrote a handbook page background piece, aimed at beginners, to
> distinguish clearly between these different "users."
>
>
> Here is the handbook page: http://drupal.org/node/660468.
>
>
> Feedback is welcomed.
>
>
> Oh, if you want to see the screencast, go
> to: http://blip.tv/dashboard/episode/2994420
> (It's long, 30 min... I should really separate out the Drupal install
> from the Drush install. But I was having fun with Screencast, which
> makes it really easy to zoom in on the part of the page you are
> emphasizing so that it is readable, even on a 640 x 480 vid.)
>
>
> Shai
> --
> 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/

Re: Handbook Page Added Re: "Users" When Installing a Drupal Site

2009-12-15T16:38:32Z

Handbook page looks good.

Won't have time to look at the screencast right away.

However, I hope you don't mind I reposted this information the NYC
drupal group as something that might be of interest to folks who
recently attended hands-on intro training at Drupal Camp NYC 7.

Hope you don't mind. If you do, let me know and I'll edit.

Here's the link

http://groups.drupal.org/node/39952

- Peter

On Tue, 2009-12-15 at 13:08 -0500, Shai Gluskin wrote:
> http://blip.tv/dashboard/episode/2994420

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

Handbook Page Added Re: "Users" When Installing a Drupal Site

2009-12-15T10:08:42Z

Yesterday, I created a screencast which is a beginners guide to installing Drupal at the command line, I noticed 4 different kinds of "users" or "user accounts" that needed mentioning: the computer user, the database user, Drupal's user/1 and all other Drupal users.

So I wrote a handbook page background piece, aimed at beginners, to distinguish clearly between these different "users."

Here is the handbook page: http://drupal.org/node/660468.

Feedback is welcomed.

Oh, if you want to see the screencast, go to: http://blip.tv/dashboard/episode/2994420

(It's long, 30 min... I should really separate out the Drupal install from the Drush install. But I was having fun with Screencast, which makes it really easy to zoom in on the part of the page you are emphasizing so that it is readable, even on a 640 x 480 vid.)

Shai

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

Re: Barriers to entry...

2009-11-30T13:36:19Z

Minor history trivia.

The older built in 'help' that existed (and was removed prior to D6 or
5, I forget) was regarding the module and site administration side of
things. Things the end user was not expected to see. At the time
(and I think still) this was the way to go. For the very reason that
Drupal is flexible, it's even harder to write generic 'end user help'
that works across a wide variety of differing site implementations.

There did exist a series of 'end user' pages in the handbook but the
real purpose of those pages was for site implementers to take and
customize to their needs and implement the relevant portions to their
own sites (not even sure if they still exist anymore). This was true
when flexinode module came out and has become even more true as more
interesting cck implementations have come out.

So, when you talk about improvements in documentation, as Shai says,
be clear up front on where / which audience your suggested
improvements are focused on.

Steven

On Sun, Nov 15, 2009 at 12:04 PM, Shai Gluskin <shai@...> wrote:

> Folks,
>
> A lot of good thinking is going on here...
>
> I'd like to put some emphasis on something we all know but may not be
> thinking about... I think it is important to disambiguate between
> "help-text" and "documentation." "Help-text, in general, are very short
> strings, often on forms or on other administrative interfaces that help
> admins or content creators fill out a form or choose settings. It exists 'in
> situ" right on the page where you are creating the content or making the
> admin choices. Documentation, on the other hand, can be printed, in a book,
> on a website (like d.o.'s handbook). I think the module help pages that we
> are reformatting now is neither help-text nor documentation. It's closer to
> documentation, but it's very, very, general and mostly not that useful.
>
> Help-text suggested fixes for Drupal core are filed in the Drupal main issue
> queue: http://drupal.org/project/issues/drupal. They are typically fixed one
> at time. And you definitely don't need ANY coding skills to notice and
> propose a change to a help-text problem. If there is consensus on the issue
> about the proposed language being better, someone will make the patch for
> you. (Note that if you have a problem with the handbook -one that can't be
> fixed by clicking on "edit" on the page in question- you can file an issue
> in the documentation issue queue at:
> http://drupal.org/project/issues/documentation. It's almost always a good
> idea to raise the issue here in the docs list serve before filing the issue
> in the documentation queue).
>
> This project of sprucing up the core module description help is raising
> bigger issues. I think the biggest issue is do we want the central
> repository of help to be encoded in Drupal or is it better outside of the
> code. I am against big ideas that would expend a lot of energy trying to get
> significant documentation into Drupal code. It would be lots of effort for
> little payoff and very difficult to maintain.
>
> I think that working on the handbook is where the biggest gains are likely
> to be made. The limbo with the d.o. re-design has impacted negatively on the
> handbook's evolution. Once the d.o. re-design launches, I think working on
> the handbook will be a LOT more fun and I think we will make faster and more
> coherent progress on it.
>
> Shai
>
>
> On Sun, Nov 15, 2009 at 2:34 PM, Ariane Khachatourians
> <arianekhachatourians@...> wrote:
>>
>> The thing with task-oriented user guides or help, is that when you start
>> getting more extensive documentation, it needs to cover more bases, and
>> that's why this has to be a well thought out process.
>>
>> All completed Drupal sites work very differently once configured, and I
>> imagine that is part of the reason why the current documentation is more
>> geared towards explaining how things function and what is possible rather
>> than step-by-step and end-user targeted.
>>
>> As someone who spent endless hours writing and updating customized
>> end-user manuals at my previous job, I know both how valuable that kind of
>> tool is to the users, but also how difficult it is to have any one guide
>> apply to even most use cases.
>>
>> It is fairly obvious that a lot of people find the current system lacking
>> though, so we should certainly try and pinpoint exactly what is lacking, and
>> what specific changes can be made to ameliorate that.
>>
>> So my suggestion here is along the lines of Jennifer's, which is that if
>> you have *specific* ideas or criticisms, please document them as issues, and
>> maybe we can declare a tag "D8help" or something of the sort. And get some
>> of the actual needs nailed down so that when the D7 work settles, we have
>> something tangible to review and base our future discussions off.
>>
>> Ariane
>>
>>
>>
>> On Sun, Nov 15, 2009 at 11:24 AM, Nancy Wichmann <nan_wich@...>
>> wrote:
>>>
>>> Shai Gluskin wrote:
>>>
>>> > MS Office... probably the best built-in help system I've seen.
>>>
>>>
>>>
>>> I sincerely hope we can do better than that. Personally, I think it has a
>>> long way to go. But maybe that’s because I am a long time power user, so
>>> when I have a question, it’s usually a doozy.
>>>
>>>
>>>
>>> The best part of that to model is the task-oriented writing. Much of
>>> Drupal’s documentation is not task-oriented.
>>>
>>>
>>>
>>> When I was working with IBM mainframes (long ago, in a galaxy far away)
>>> we had a “User’s Guide” and a “User’s Reference” for most things. The Guide
>>> was lower level, and mostly task oriented, while the Reference was
>>> function-oriented, more like DO.
>>>
>>>
>>>
>>>
>>>
>>> Nancy E. Wichmann, PMP
>>>
>>> Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L.
>>> King, Jr.
>>>
>>> --
>>> 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/
>

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

Re: String freeze Dec 1st!

2009-11-28T00:47:55Z

Steve,

All the help-file texts of the modules that will appear in Drupal7 are
being reviewed, discussed and improved via this issue queue :

http://drupal.org/project/issues/search/drupal?text=&assigned=&submitted=&participant=&version[]=7.x&issue_tags_op=or&issue_tags=d7help

You can review the texts and submit improvements in the comments
section of each issue.

Each issue includes screenshots that show what the result will look
like after the suggested text changes are applied.

Go check out the queue.

Boris.

2009/11/28 Ariane Khachatourians <arianekhachatourians@...>:

> Hi Steve -
>
> I'm not sure I totally understand what you're asking, ie. what part of the
> process you need more info about.
>
> That said - if you think that a section of text needs updating, you can post
> an issue for it on the issue queue http://drupal.org/node/add/project-issue
> and post a patch there. If it's a major change (not just fixing a
> grammatical error), it will need to be discussed/reviewed/okayed by other
> members of the doc team or whoever works on that project.
>
> This Tuesday is a deadline for changing strings though, so that translators
> can start their work, so the patch would have to be reviewed and committed
> by then if it is more than just a bug.
>
> Hope that helps,
> Ariane
>
>
>
> On Fri, Nov 27, 2009 at 9:24 AM, Steve Kessler <skessler@...>
> wrote:
>>
>> How do we submit patches for specific strings...like the explanation of
>> cron
>> on admin/config/system/site-information
>>
>> Thanks,
>> Steve
>>
>> Steve Kessler
>> Denver DataMan
>> 303-587-4428
>> Sign up for the Denver DataMan Free eNewsletter
>>
>>
>> -----Original Message-----
>> From: Jennifer Hodgdon [mailto:yahgrp@...]
>> Sent: Thursday, November 19, 2009 10:36 PM
>> To: A list for documentation writers
>> Subject: [documentation] String freeze Dec 1st!
>>
>> Hello Doc Team,
>>
>> I just want to say first how exciting it has been that so many of you
>> pitched in to help with the help system overview! Tremendous progress
>> has been made; now it's mostly a matter of reviewing/updating patches
>> and getting them committed. See http://drupal.org/node/537828 if you
>> are curious about what's been happening and get involved.
>>
>> Anyway... I found out today that the upcoming User Experience (UX)
>> freeze for Drupal 7 is also supposed to include a "string freeze".
>> Which is to say, all of the text within Drupal 7 that needs to be
>> translated (help text and user interface text) is supposed to be
>> frozen on December 1st -- less than 2 weeks away -- aside from "bugs"
>> (which after December 1st means just spelling and minor grammatical
>> errors, not totally rewriting or rearranging). That includes the D7
>> help effort!
>>
>> So, I would like to suggest that both programming and non-programming
>> members of the Drupal Documentation team (this means you, if you are
>> subscribed to this email list) -- if you have some free time between
>> now and December 1st, you can try:
>>
>> a) Installing Drupal 7 (you can download the latest version at
>> http://drupal.org/project/drupal if you are not using CVS) and
>> reviewing the text you see on its user interface and help. My
>> suggestion is to enable all of the core modules (especially the Help
>> module), try out some of the features/tasks/screens, and if you find
>> something in the user interface that doesn't make sense, file an issue.
>>
>> Hints on filing an issue:
>> - Start from http://drupal.org/node/add/project-issue/drupal
>> - Version: 7.x
>> - Component: The module or theme the problem is in, or "documentation"
>> if it is in a help file.
>> - Category: Bug report
>> - It is very helpful to put in a good summary in the Title, and a full
>> description of the problem you saw, where you saw it (what screen --
>> give the Drupal path), when you saw it (if you had to enter or do
>> something to get this bad text to appear), why you think it is bad,
>> and if possible your suggested better text.
>>
>> b) Reviewing proposed patches. Search using the Advanced Search
>> interface starting at http://drupal.org/project/issues/search/drupal
>> for issues that have status "needs review", version 7.x, and one of
>> the following:
>> - Tagged with "ui-text" [without the quotes, of course]
>> - Tagged with "Help text"
>> - Tagged with "d7help"
>>
>> Hints on patch review:
>> - Even if you are not a programmer, you can still review the text in
>> these patches. Scroll down to the bottom of the issue's comments, and
>> find the latest patch attachment. Click on the attachment, and the
>> lines with + are being added, lines with - are being removed.
>> - If you think the patch is good, add a comment saying what part you
>> reviewed and that you thought it was good.
>> - If you think the patch needs some work, change the status of the
>> issue to "needs work", and add a specific comment about what you think
>> should be changed (if possible, with a suggestion of what to change it
>> to).
>>
>> c) Participate in the D7 Usability sprint this weekend if you can:
>> http://webchick.net/node/72
>>
>> Thanks, and keep up the good work!
>>
>> --Jennifer
>>
>> ps: If you need help with filing issues or reviewing patches, you can
>> get advice from the doc team on our IRC channel - #drupal-docs. See
>> http://groups.drupal.org/node/2326 for info on IRC if you don't know
>> how to connect. There are also useful links on
>> http://drupal.org/node/540308
>>
>> --
>> Jennifer Hodgdon * Poplar ProductivityWare
>> www.poplarware.com
>> Drupal, WordPress, and custom Web programming
>>
>> --
>> 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/
>

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

Re: String freeze Dec 1st!

2009-11-27T16:57:09Z

Hi Steve -

I'm not sure I totally understand what you're asking, ie. what part of the process you need more info about.

That said - if you think that a section of text needs updating, you can post an issue for it on the issue queue http://drupal.org/node/add/project-issue and post a patch there. If it's a major change (not just fixing a grammatical error), it will need to be discussed/reviewed/okayed by other members of the doc team or whoever works on that project.

This Tuesday is a deadline for changing strings though, so that translators can start their work, so the patch would have to be reviewed and committed by then if it is more than just a bug.

Hope that helps,
Ariane

On Fri, Nov 27, 2009 at 9:24 AM, Steve Kessler <skessler@...> wrote:

How do we submit patches for specific strings...like the explanation of cron
on admin/config/system/site-information

Thanks,
Steve

Steve Kessler
Denver DataMan
303-587-4428
Sign up for the Denver DataMan Free eNewsletter

-----Original Message-----
From: Jennifer Hodgdon [mailto:yahgrp@...]
Sent: Thursday, November 19, 2009 10:36 PM
To: A list for documentation writers
Subject: [documentation] String freeze Dec 1st!

Hello Doc Team,

I just want to say first how exciting it has been that so many of you
pitched in to help with the help system overview! Tremendous progress
has been made; now it's mostly a matter of reviewing/updating patches
and getting them committed. See http://drupal.org/node/537828 if you
are curious about what's been happening and get involved.

Anyway... I found out today that the upcoming User Experience (UX)
freeze for Drupal 7 is also supposed to include a "string freeze".
Which is to say, all of the text within Drupal 7 that needs to be
translated (help text and user interface text) is supposed to be
frozen on December 1st -- less than 2 weeks away -- aside from "bugs"
(which after December 1st means just spelling and minor grammatical
errors, not totally rewriting or rearranging). That includes the D7
help effort!

So, I would like to suggest that both programming and non-programming
members of the Drupal Documentation team (this means you, if you are
subscribed to this email list) -- if you have some free time between
now and December 1st, you can try:

a) Installing Drupal 7 (you can download the latest version at
http://drupal.org/project/drupal if you are not using CVS) and
reviewing the text you see on its user interface and help. My
suggestion is to enable all of the core modules (especially the Help
module), try out some of the features/tasks/screens, and if you find
something in the user interface that doesn't make sense, file an issue.

Hints on filing an issue:
- Start from http://drupal.org/node/add/project-issue/drupal
- Version: 7.x
- Component: The module or theme the problem is in, or "documentation"
if it is in a help file.
- Category: Bug report
- It is very helpful to put in a good summary in the Title, and a full
description of the problem you saw, where you saw it (what screen --
give the Drupal path), when you saw it (if you had to enter or do
something to get this bad text to appear), why you think it is bad,
and if possible your suggested better text.

b) Reviewing proposed patches. Search using the Advanced Search
interface starting at http://drupal.org/project/issues/search/drupal
for issues that have status "needs review", version 7.x, and one of
the following:
- Tagged with "ui-text" [without the quotes, of course]
- Tagged with "Help text"
- Tagged with "d7help"

Hints on patch review:
- Even if you are not a programmer, you can still review the text in
these patches. Scroll down to the bottom of the issue's comments, and
find the latest patch attachment. Click on the attachment, and the
lines with + are being added, lines with - are being removed.
- If you think the patch is good, add a comment saying what part you
reviewed and that you thought it was good.
- If you think the patch needs some work, change the status of the
issue to "needs work", and add a specific comment about what you think
should be changed (if possible, with a suggestion of what to change it
to).

c) Participate in the D7 Usability sprint this weekend if you can:
http://webchick.net/node/72

Thanks, and keep up the good work!

--Jennifer

ps: If you need help with filing issues or reviewing patches, you can
get advice from the doc team on our IRC channel - #drupal-docs. See
http://groups.drupal.org/node/2326 for info on IRC if you don't know
how to connect. There are also useful links on
http://drupal.org/node/540308

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: String freeze Dec 1st!

2009-11-27T09:24:49Z

How do we submit patches for specific strings...like the explanation of cron
on admin/config/system/site-information

Thanks,
Steve

Steve Kessler
Denver DataMan
303-587-4428
Sign up for the Denver DataMan Free eNewsletter

-----Original Message-----
From: Jennifer Hodgdon [mailto:yahgrp@...]
Sent: Thursday, November 19, 2009 10:36 PM
To: A list for documentation writers
Subject: [documentation] String freeze Dec 1st!

Hello Doc Team,

I just want to say first how exciting it has been that so many of you
pitched in to help with the help system overview! Tremendous progress
has been made; now it's mostly a matter of reviewing/updating patches
and getting them committed. See http://drupal.org/node/537828 if you
are curious about what's been happening and get involved.

Anyway... I found out today that the upcoming User Experience (UX)
freeze for Drupal 7 is also supposed to include a "string freeze".
Which is to say, all of the text within Drupal 7 that needs to be
translated (help text and user interface text) is supposed to be
frozen on December 1st -- less than 2 weeks away -- aside from "bugs"
(which after December 1st means just spelling and minor grammatical
errors, not totally rewriting or rearranging). That includes the D7
help effort!

So, I would like to suggest that both programming and non-programming
members of the Drupal Documentation team (this means you, if you are
subscribed to this email list) -- if you have some free time between
now and December 1st, you can try:

a) Installing Drupal 7 (you can download the latest version at
http://drupal.org/project/drupal if you are not using CVS) and
reviewing the text you see on its user interface and help. My
suggestion is to enable all of the core modules (especially the Help
module), try out some of the features/tasks/screens, and if you find
something in the user interface that doesn't make sense, file an issue.

Hints on filing an issue:
- Start from http://drupal.org/node/add/project-issue/drupal
- Version: 7.x
- Component: The module or theme the problem is in, or "documentation"
if it is in a help file.
- Category: Bug report
- It is very helpful to put in a good summary in the Title, and a full
description of the problem you saw, where you saw it (what screen --
give the Drupal path), when you saw it (if you had to enter or do
something to get this bad text to appear), why you think it is bad,
and if possible your suggested better text.

b) Reviewing proposed patches. Search using the Advanced Search
interface starting at http://drupal.org/project/issues/search/drupal
for issues that have status "needs review", version 7.x, and one of
the following:
- Tagged with "ui-text" [without the quotes, of course]
- Tagged with "Help text"
- Tagged with "d7help"

Hints on patch review:
- Even if you are not a programmer, you can still review the text in
these patches. Scroll down to the bottom of the issue's comments, and
find the latest patch attachment. Click on the attachment, and the
lines with + are being added, lines with - are being removed.
- If you think the patch is good, add a comment saying what part you
reviewed and that you thought it was good.
- If you think the patch needs some work, change the status of the
issue to "needs work", and add a specific comment about what you think
should be changed (if possible, with a suggestion of what to change it
to).

c) Participate in the D7 Usability sprint this weekend if you can:
http://webchick.net/node/72

Thanks, and keep up the good work!

--Jennifer

ps: If you need help with filing issues or reviewing patches, you can
get advice from the doc team on our IRC channel - #drupal-docs. See
http://groups.drupal.org/node/2326 for info on IRC if you don't know
how to connect. There are also useful links on
http://drupal.org/node/540308

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

String freeze Dec 1st!

2009-11-19T21:36:12Z

Hello Doc Team,

I just want to say first how exciting it has been that so many of you
pitched in to help with the help system overview! Tremendous progress
has been made; now it's mostly a matter of reviewing/updating patches
and getting them committed. See http://drupal.org/node/537828 if you
are curious about what's been happening and get involved.

Anyway... I found out today that the upcoming User Experience (UX)
freeze for Drupal 7 is also supposed to include a "string freeze".
Which is to say, all of the text within Drupal 7 that needs to be
translated (help text and user interface text) is supposed to be
frozen on December 1st -- less than 2 weeks away -- aside from "bugs"
(which after December 1st means just spelling and minor grammatical
errors, not totally rewriting or rearranging). That includes the D7
help effort!

So, I would like to suggest that both programming and non-programming
members of the Drupal Documentation team (this means you, if you are
subscribed to this email list) -- if you have some free time between
now and December 1st, you can try:

a) Installing Drupal 7 (you can download the latest version at
http://drupal.org/project/drupal if you are not using CVS) and
reviewing the text you see on its user interface and help. My
suggestion is to enable all of the core modules (especially the Help
module), try out some of the features/tasks/screens, and if you find
something in the user interface that doesn't make sense, file an issue.

Hints on filing an issue:
- Start from http://drupal.org/node/add/project-issue/drupal
- Version: 7.x
- Component: The module or theme the problem is in, or "documentation"
if it is in a help file.
- Category: Bug report
- It is very helpful to put in a good summary in the Title, and a full
description of the problem you saw, where you saw it (what screen --
give the Drupal path), when you saw it (if you had to enter or do
something to get this bad text to appear), why you think it is bad,
and if possible your suggested better text.

b) Reviewing proposed patches. Search using the Advanced Search
interface starting at http://drupal.org/project/issues/search/drupal
for issues that have status "needs review", version 7.x, and one of
the following:
- Tagged with "ui-text" [without the quotes, of course]
- Tagged with "Help text"
- Tagged with "d7help"

Hints on patch review:
- Even if you are not a programmer, you can still review the text in
these patches. Scroll down to the bottom of the issue's comments, and
find the latest patch attachment. Click on the attachment, and the
lines with + are being added, lines with - are being removed.
- If you think the patch is good, add a comment saying what part you
reviewed and that you thought it was good.
- If you think the patch needs some work, change the status of the
issue to "needs work", and add a specific comment about what you think
should be changed (if possible, with a suggestion of what to change it
to).

c) Participate in the D7 Usability sprint this weekend if you can:
http://webchick.net/node/72

Thanks, and keep up the good work!

--Jennifer

ps: If you need help with filing issues or reviewing patches, you can
get advice from the doc team on our IRC channel - #drupal-docs. See
http://groups.drupal.org/node/2326 for info on IRC if you don't know
how to connect. There are also useful links on
http://drupal.org/node/540308

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-15T12:04:48Z

Folks,

A lot of good thinking is going on here...

I'd like to put some emphasis on something we all know but may not be thinking about... I think it is important to disambiguate between "help-text" and "documentation." "Help-text, in general, are very short strings, often on forms or on other administrative interfaces that help admins or content creators fill out a form or choose settings. It exists 'in situ" right on the page where you are creating the content or making the admin choices. Documentation, on the other hand, can be printed, in a book, on a website (like d.o.'s handbook). I think the module help pages that we are reformatting now is neither help-text nor documentation. It's closer to documentation, but it's very, very, general and mostly not that useful.

Help-text suggested fixes for Drupal core are filed in the Drupal main issue queue: http://drupal.org/project/issues/drupal. They are typically fixed one at time. And you definitely don't need ANY coding skills to notice and propose a change to a help-text problem. If there is consensus on the issue about the proposed language being better, someone will make the patch for you. (Note that if you have a problem with the handbook -one that can't be fixed by clicking on "edit" on the page in question- you can file an issue in the documentation issue queue at: http://drupal.org/project/issues/documentation. It's almost always a good idea to raise the issue here in the docs list serve before filing the issue in the documentation queue).

This project of sprucing up the core module description help is raising bigger issues. I think the biggest issue is do we want the central repository of help to be encoded in Drupal or is it better outside of the code. I am against big ideas that would expend a lot of energy trying to get significant documentation into Drupal code. It would be lots of effort for little payoff and very difficult to maintain.

I think that working on the handbook is where the biggest gains are likely to be made. The limbo with the d.o. re-design has impacted negatively on the handbook's evolution. Once the d.o. re-design launches, I think working on the handbook will be a LOT more fun and I think we will make faster and more coherent progress on it.

Shai

On Sun, Nov 15, 2009 at 2:34 PM, Ariane Khachatourians <arianekhachatourians@...> wrote:

The thing with task-oriented user guides or help, is that when you start getting more extensive documentation, it needs to cover more bases, and that's why this has to be a well thought out process.

All completed Drupal sites work very differently once configured, and I imagine that is part of the reason why the current documentation is more geared towards explaining how things function and what is possible rather than step-by-step and end-user targeted.

As someone who spent endless hours writing and updating customized end-user manuals at my previous job, I know both how valuable that kind of tool is to the users, but also how difficult it is to have any one guide apply to even most use cases.

It is fairly obvious that a lot of people find the current system lacking though, so we should certainly try and pinpoint exactly what is lacking, and what specific changes can be made to ameliorate that.

So my suggestion here is along the lines of Jennifer's, which is that if you have *specific* ideas or criticisms, please document them as issues, and maybe we can declare a tag "D8help" or something of the sort. And get some of the actual needs nailed down so that when the D7 work settles, we have something tangible to review and base our future discussions off.

Ariane

On Sun, Nov 15, 2009 at 11:24 AM, Nancy Wichmann <nan_wich@...> wrote:

Shai Gluskin wrote:

> MS Office... probably the best built-in help system I've seen.

I sincerely hope we can do better than that. Personally, I think it has a long way to go. But maybe that’s because I am a long time power user, so when I have a question, it’s usually a doozy.

The best part of that to model is the task-oriented writing. Much of Drupal’s documentation is not task-oriented.

When I was working with IBM mainframes (long ago, in a galaxy far away) we had a “User’s Guide” and a “User’s Reference” for most things. The Guide was lower level, and mostly task oriented, while the Reference was function-oriented, more like DO.

Nancy E. Wichmann, PMP

Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.

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

Re: Barriers to entry...

2009-11-15T11:34:40Z

The thing with task-oriented user guides or help, is that when you start getting more extensive documentation, it needs to cover more bases, and that's why this has to be a well thought out process.

All completed Drupal sites work very differently once configured, and I imagine that is part of the reason why the current documentation is more geared towards explaining how things function and what is possible rather than step-by-step and end-user targeted.

As someone who spent endless hours writing and updating customized end-user manuals at my previous job, I know both how valuable that kind of tool is to the users, but also how difficult it is to have any one guide apply to even most use cases.

It is fairly obvious that a lot of people find the current system lacking though, so we should certainly try and pinpoint exactly what is lacking, and what specific changes can be made to ameliorate that.

So my suggestion here is along the lines of Jennifer's, which is that if you have *specific* ideas or criticisms, please document them as issues, and maybe we can declare a tag "D8help" or something of the sort. And get some of the actual needs nailed down so that when the D7 work settles, we have something tangible to review and base our future discussions off.

Ariane

On Sun, Nov 15, 2009 at 11:24 AM, Nancy Wichmann <nan_wich@...> wrote:

Shai Gluskin wrote:

> MS Office... probably the best built-in help system I've seen.

I sincerely hope we can do better than that. Personally, I think it has a long way to go. But maybe that’s because I am a long time power user, so when I have a question, it’s usually a doozy.

The best part of that to model is the task-oriented writing. Much of Drupal’s documentation is not task-oriented.

When I was working with IBM mainframes (long ago, in a galaxy far away) we had a “User’s Guide” and a “User’s Reference” for most things. The Guide was lower level, and mostly task oriented, while the Reference was function-oriented, more like DO.

Nancy E. Wichmann, PMP

Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.

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

Re: Barriers to entry...

2009-11-15T11:24:15Z

Shai Gluskin wrote:

> MS Office... probably the best built-in help system I've seen.

I sincerely hope we can do better than that. Personally, I think it has a long way to go. But maybe that’s because I am a long time power user, so when I have a question, it’s usually a doozy.

The best part of that to model is the task-oriented writing. Much of Drupal’s documentation is not task-oriented.

When I was working with IBM mainframes (long ago, in a galaxy far away) we had a “User’s Guide” and a “User’s Reference” for most things. The Guide was lower level, and mostly task oriented, while the Reference was function-oriented, more like DO.

Nancy E. Wichmann, PMP

Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.

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

User guide/better help in D7

2009-11-15T08:07:20Z

Steve Kessler wrote:
> I think that is critical that there is some amount of help that ships with
> Drupal. But this could be 2 or 3 sentences and a link to a page. Does the
> research from D7UX tell us anything that we should take into account?

I can't address D7UX in regards to help...

But regarding your other comment, there is already "some amount of
help" shipping with Drupal. If you think that what we currently have
in Drupal 7 for help is misleading, not detailed enough, too detailed,
inadequate, missing information, or otherwise needs to be revised (and
I'm not saying I would disagree), then NOW is the time to bring it up.
There is zero chance any help will change in Drupal 6, but Drupal 7 is
still in development.

I need to say a bit about process here, though: Nothing will get done
on this if it is not brought up in the right way.

a) Must be specific. A vague "we need more help" idea or "we need a
user guide" will not be addressed. Specifics such as "This screen
needs to explain xyz" or "The main Help page needs to state abc" may
be addressed.

b) Needs a patch: Someone eventually needs to supply not only a
specific description of the problem, but also a solution (patch), if
you want the problem to be solved in Drupal.

c) Issue Queue: Both the problem and the solution have to be presented
in the issue queue, and go through the issue review process, in order
to make it into Drupal. Discussing it here or in the #drupal-doc IRC
is fine as a first step, but if it never gets into the Drupal issue
queue, it will not be incorporated into Drupal.

- Schedule: The development of Drupal happens on a schedule. If it
requires some major "user experience" change (e.g. major reformatting
of help text), it needs to happen before December 1st. If it is just a
matter of adding/changing text that already exists, then there is a
bit more time, but not a lot (would need to go in before "string freeze").

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-15T07:49:32Z

Lee and Jennifer and all,

I agree with Jennifer that the online handbook is the best way to go. This current effort will make Drupal look slicker and it will be of some marginal help, but it doesn't tackle the bigger issue.

For D8 I think we should advocate for A LOT more references within the Drupal install to d.o. handbook pages. That gives people good references inside the ap, but allows the info to be current since handbook pages are constantly up-datable, and there is no technical barrier to entry.

Something I thought of in the shower last night..

I love Mac OS X... terrible built-in help system
I hate MS Office... probably the best built-in help system I've seen.
I love Drupal... I've attempted a few times to use the built-in help system and found it unsatisfying. Maybe three times in 3 years, and I'm probably seeking Drupal info every single one of those days.

In short, I think the handbook is the way to go...

And that's not to minimize this push to do a modest improvement to the built in help system. I'm just alerting non-coders that I don't think this is really where the action is.

Shai

On Sun, Nov 15, 2009 at 10:37 AM, Jennifer Hodgdon <yahgrp@...> wrote:

Lee Hunter wrote:
> We're calling this a "help" system but that's not at all what's being
> written. It would be much more accurate to call it a "Module Reference".
>
> Help system content is normally all about the user - what the user wants to

> achieve and the tasks that they want to perform [...]

I agree, Lee: Definitely the main module pages that we are editing are
a module reference and not a user guide. The other entries in
hook_help() implementations (which are help text that can be displayed
on individual screens the module provides) are more in the line of
"user guide", but they certainly don't constitute a full user guide.
And hook_help() is never going to be a good vehicle for creating a
full user guide.

I will just note that the effort to revamp the current Drupal help
system (perhaps in line with the Advanced Help contrib module) failed
for D7 (I'm not familiar with exactly why)... and now is definitely
the time to start thinking about what architecture would make sense
for D8.

But I am not sure we want to ship a user guide with Drupal at all,
really -- maybe we should stick with the on-line Handbook (or some
small, official subset) as the official user guide. This would have
several advantages:
- Non-coders can edit.
- Few barriers to doc writers to contribute.
- Much more dynamic than Drupal releases. Anything distributed with
Drupal has to be translated into many languages, which pretty much
means it is set in stone once a major release is out, and cannot
(except for major bugs) be revised for minor Drupal versions.
- Searchable via search on d.o as well as web search engines.
- Can recommend contrib modules to achieve goals that are
difficult/impossible with just core Drupal.

Thoughts?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-15T07:45:09Z

Ariane Khachatourians wrote:
> Re: Barriers to entry [...]

> I would hope that most people *would* have an inclination to learn further
> (and if they choose not to, then that is a fair choice). [...]

> 1. Having someone walk me through setting up a local install on MAMP, use
> PHPmyadmin, and getting a basic list of what commands I needed to know in
> command line.
>
> 2. Having the issue queue/patch review workflow explained and shown to me,
> along with learning the commands to apply and revert patches, do a diff, and
> reset my codebase to HEAD.
>
> 3. And this is not *necessary* but having at least a willingness to learn to
> read (and hopefully one day, write, code). I have so far self-learned HTML
> and CSS (with help from friends and coworkers), and can sort of fumble my
> way through reading PHP to the point where I can cut and paste things into
> the right place. But that is something people have to be pretty self driven
> to accomplish.

Maybe we should have some sessions on these things at DCSF? I guess it
merits several sessions:

a) Setting up a test box (WinAMP, MAMP, LAMP) for Drupal, including
PHPMyAdmin and command-line basics.

b) CVS basics (getting CVS set up, making patches, commands, updating
your Drupal installation, etc.), and finding your way around the issue
queue.

c) Basics of PHP for doc writers and themers (with the aim of being
able to understand what it is doing, and edit text/markup embedded in
the code).

Thoughts? I could do B and C; not so sure about (a), as I only know
about LAMP on Ubuntu. And maybe (b) is too much for one session, and
it should be split into two parts?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-15T07:42:40Z

I think that is critical that there is some amount of help that ships with
Drupal. But this could be 2 or 3 sentences and a link to a page. Does the
research from D7UX tell us anything that we should take into account?

Thanks,
Steve

Steve Kessler
Denver DataMan
303-587-4428

-----Original Message-----
From: Jennifer Hodgdon [mailto:yahgrp@...]
Sent: Sunday, November 15, 2009 8:38 AM
To: A list for documentation writers
Subject: Re: [documentation] Barriers to entry...

Lee Hunter wrote:
> We're calling this a "help" system but that's not at all what's being
> written. It would be much more accurate to call it a "Module Reference".
>
> Help system content is normally all about the user - what the user wants
to
> achieve and the tasks that they want to perform [...]

I agree, Lee: Definitely the main module pages that we are editing are
a module reference and not a user guide. The other entries in
hook_help() implementations (which are help text that can be displayed
on individual screens the module provides) are more in the line of
"user guide", but they certainly don't constitute a full user guide.
And hook_help() is never going to be a good vehicle for creating a
full user guide.

I will just note that the effort to revamp the current Drupal help
system (perhaps in line with the Advanced Help contrib module) failed
for D7 (I'm not familiar with exactly why)... and now is definitely
the time to start thinking about what architecture would make sense
for D8.

But I am not sure we want to ship a user guide with Drupal at all,
really -- maybe we should stick with the on-line Handbook (or some
small, official subset) as the official user guide. This would have
several advantages:
- Non-coders can edit.
- Few barriers to doc writers to contribute.
- Much more dynamic than Drupal releases. Anything distributed with
Drupal has to be translated into many languages, which pretty much
means it is set in stone once a major release is out, and cannot
(except for major bugs) be revised for minor Drupal versions.
- Searchable via search on d.o as well as web search engines.
- Can recommend contrib modules to achieve goals that are
difficult/impossible with just core Drupal.

Thoughts?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-15T07:36:36Z

Lee Hunter wrote:
> We're calling this a "help" system but that's not at all what's being
> written. It would be much more accurate to call it a "Module Reference".
>
> Help system content is normally all about the user - what the user wants to
> achieve and the tasks that they want to perform [...]

I agree, Lee: Definitely the main module pages that we are editing are
a module reference and not a user guide. The other entries in
hook_help() implementations (which are help text that can be displayed
on individual screens the module provides) are more in the line of
"user guide", but they certainly don't constitute a full user guide.
And hook_help() is never going to be a good vehicle for creating a
full user guide.

I will just note that the effort to revamp the current Drupal help
system (perhaps in line with the Advanced Help contrib module) failed
for D7 (I'm not familiar with exactly why)... and now is definitely
the time to start thinking about what architecture would make sense
for D8.

But I am not sure we want to ship a user guide with Drupal at all,
really -- maybe we should stick with the on-line Handbook (or some
small, official subset) as the official user guide. This would have
several advantages:
- Non-coders can edit.
- Few barriers to doc writers to contribute.
- Much more dynamic than Drupal releases. Anything distributed with
Drupal has to be translated into many languages, which pretty much
means it is set in stone once a major release is out, and cannot
(except for major bugs) be revised for minor Drupal versions.
- Searchable via search on d.o as well as web search engines.
- Can recommend contrib modules to achieve goals that are
difficult/impossible with just core Drupal.

Thoughts?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Barriers to entry...

2009-11-14T11:46:36Z

Re: Barriers to entry

Jennifer, I found it incredibly helpful having the PHP and HTML posted on the standard page - being that I can write HTML but not PHP, but am marginally PHP literate, that (and peeking at the patch you posted for a few other hints) was enough for me to be able to adapt a help function on my own, which to me is amazing! (And the closest I've come to writing any PHP code.)

I don't really consider myself a "developer", and wanted to be able to go further than just editing online docs, and I have been able to, but it of course required effort and a willingness to learn new tools. And it always will, because let's face it, this a web application, and it is made of code! No matter how advanced our APIs get, there is always going to be some things you can't access or work on without working in the code itself.

I would hope that most people *would* have an inclination to learn further (and if they choose not to, then that is a fair choice). What I found incredibly helpful getting to the point where, as still a non-developer (ie. I don't know how to write PHP code) was this (and these 3 things seem less scary as separate steps, so maybe focus on #1 and #2 as separate sessions):

1. Having someone walk me through setting up a local install on MAMP, use PHPmyadmin, and getting a basic list of what commands I needed to know in command line.

2. Having the issue queue/patch review workflow explained and shown to me, along with learning the commands to apply and revert patches, do a diff, and reset my codebase to HEAD.

3. And this is not *necessary* but having at least a willingness to learn to read (and hopefully one day, write, code). I have so far self-learned HTML and CSS (with help from friends and coworkers), and can sort of fumble my way through reading PHP to the point where I can cut and paste things into the right place. But that is something people have to be pretty self driven to accomplish.

The biggest challenge is finding a way to make these things seem exciting to people rather than scary, and the only thing I can attribute that to for me is having very enthusiastic and patient people around me who have made certain I didn't get discouraged.

Re: How to conceptualize the help system

Is there an issue filed on d.o somewhere about this? It's not been on my radar - and I can only assume this is past the eleventh hour for D7 to try and make that sort of a conceptual shift. But that doesn't mean it's not something worth thinking about some more.

And really, I do think the new structure of the help content accommodates that user-focused approach better. The About section, being about what the module does, and the Uses section telling you how it can be used. No, it doesn't give you a step-by-step on how to do things, but that is in the handbook.

Ariane

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

Re: Improving help pages in D7

2009-11-14T11:17:48Z

Like I mentioned earlier, if someone has module documentation written
I am all too happy to roll a patch, if CVS is indeed the barrier. Just
make sure you mention your drupal.org ID. There are enough people who
know how to use CVS that can do the heavy lifting by partnering up
with people that aren't comfortable with CVS, diff and patch.

Samir Nassar
612-481-0843
samir.nassar@...
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

Re: Improving help pages in D7

2009-11-14T11:07:31Z

When it comes down to it, the issue of how the text is edited is really an entirely different discussion than how to restructure the help content.

At the risk of sounding like a broken record, the timeline is much too short for this issue (we have just over 2 weeks) to change the way the help documentation works - I'm sure if you want to sign up to rewrite help text for a module with the new format, and post it as a comment, someone else can put it into the PHP code and roll the patch.

But to be honest, like Jennifer said on the other thread that was started on barriers to contributing, there are many other really useful places you can help that do not require going into the code or rolling patches. She put several examples in her reply that I think are worth going through if you want to help out more!

Ariane

On Sat, Nov 14, 2009 at 5:06 AM, adept digital evolution <techlists@...> wrote:

I have to agree. There should be an easier way to participate for
non-developers who, like myself, know nothing of CVS systems or patches
or php, and who do not have time or inclination to learn that end of
things, but who (also like myself) might be quite good at helping to
author and organize good help documentation.

I've pretty much given up on helping with docs because I click links
from this discussion list to look at an issue, and then have absolutely
no idea what to do. It looks like I'd have to know php, to know how to
check out items from some repository somewhere (where?), how to write
something called a "patch", how to test it, and so on. This is just not
my profession. The whole approach pretty much freezes just regular old
consultants and writers from your process.

I had done much work on he D7 install guide (the online version) and
therefore offered to also review the install.txt document that gets
included with the downloaded installer , but for some reason this is
much more complicated than just editing a text document. I didn't know
where to get it or what the heck to do with it. I used up my time trying
to figure all that out without ever even finding it.

I will continue to edit any d.o doc pages that I might have priv's to
edit. But I hope some day editing help text is as easy as editing
anything on d.o

kazar

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

Re: Barriers to entry...

2009-11-14T08:46:07Z

Lee Hunter wrote:

> We're calling this a "help" system but that's not at all what's being written. It would be much more accurate to call it a "Module Reference".

> Help system content is normally all about the user

I believe we actually need both. And the two forms need to be written for, and by, different audiences. While I can agree that the current “reference” is more for developers, the Advanced Help module is better geared for the user. Unfortunately, it is the developer, who is generally unsuited or unwilling to do that documentation, who is in the best position to provide it – or at least the implementation to provide it. For the time being, I suspect we will have to continue relying on the handbooks for this.

It could be useful, however, to encourage those who are better suited for the handbooks to also work with the developers to develop Advanced Help. They could provide the text and point to where it is needed; the developer can then do the relatively simple steps to implement that help.

Nancy E. Wichmann, PMP

Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.

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

Re: Barriers to entry...

2009-11-14T08:21:10Z

I appreciate that it's not practical to inject some new steps into the process at this point in time. The important thing is that it gets done.

There is one other thing, though, that I have a problem with. I hesitate to bring this up, because again it may be a bit late to deal with but it is a really important ussue so I think it's worth bringing up any time. Actually, I did try to raise this point when the new Help system was being developed but I couldn't get any traction. However, since we're talking about help, here's my concern, for what its worth.

We're calling this a "help" system but that's not at all what's being written. It would be much more accurate to call it a "Module Reference".

Help system content is normally all about the user - what the user wants to achieve and the tasks that they want to perform whereas this content that's being developed is really describing the architecture of the software itself (here are the modules and here's what they do), information which is of very limited value to the user. It generally wouldn't appear at all in a typical Help system and if it did, it would be in the final section, as an appendix.

I know that there will be links here and there to various admin pages but that still isn't what the user would expect to see in Help. The Node module example really illustrates my point. The node module is merely part of the architecture, whereas most users will open the Help in the hopes that they will learn how to perform a specific content-related task or reach a content-related goal. How do I add a page? Manage content? I don't care what the software is doing, I'm only interested in what I'm trying to do.

Having said, for better or worse, we've already decided to go down this module-centric road with D7 so I don't think there's any way of changing the way things are structured. But I do think, as this new content is being written, we can start incorporating this principle of writing from the user's perspective rather than the module developer's perspective. Rather than write "The x module does this that and the other thing" start off with something like this: "When the foobar module is enabled, you can create an x and manage a y. " and for something like the Node module, keep the same pattern but change the wording to something like "The node module is always enabled. It is the part of Drupal that enables you to create and manage content. To add new content, click ... To manage content click ..."

It may be a long time before we make the inevitable step of structuring the Help around the user - perhaps not till D8 or 9, but there's no reason why we can't start writing that way immediately.

Lee

2009/11/14 Jennifer Hodgdon <yahgrp@...>

Regarding the process and getting non-programmers involved in the help
screens and text in general in Drupal....

For this patch we're working on -- there isn't time to get a new
process in place, because of the time frame. But I agree that there is
a VERY high perceived barrier for non-programmers to help with
documentation in Drupal. This is also a problem for designers who
might want to contribute to themes.

I do have a couple of suggestions for how non-programmers can get
involved and help out with Drupal documentation (more at
http://drupal.org/node/540308):

a) Non-programmers can definitely contribute to the Handbook
documentation on drupal.org. There is a suggested list of ways to
contribute to the Handbook at http://drupal.org/node/302146 and none
of those ideas requires you to "roll patches", work in PHP, etc.

b) If you see problems in the help text or user interface text within
Drupal, you can file an issue. Even if you do not know how to create a
patch, you can still give before/after text suggestions, and someone
else can create the patch. To do that:
- Click on "Create Content" on the sidebar on drupal.org
- Choose "Drupal" as the project
- Choose the Drupal version. Note that for right now, pretty much
only 7.x issues will be addressed -- it is REALLY difficult to get
text changes into 6.x at this point, if not possible.
- Choose component "user interface text" or "documentation", as
appropriate.
- Choose category "bug report" -- text being wrong, missing, or
unclear is a bug, not a feature request or task.
- Make up a clear title and description, and submit your issue.

c) To help with existing issues, search the issue queue for the Drupal
project, component "documentation" or "user interface text" or tag
"Help text" or tag "ui-text". Be aware that most of the issues filed
under component "documentation" are issues with the in-line programmer
API documentation of functions in the source code (displayed on
api.drupal.org), so if you are not a programmer, these will not be
things you will probably want to work on. Even if you cannot write
patches, you can still review patches and make suggestions on how to
improve text, by commenting on issues.

Thoughts?

I was thinking maybe it would be a good idea to propose a session at
DCSF to get non-programmers up to speed on patching, but then I read
one of the commenters saying "no inclination" to learn that...
Definitely, the formatting needed for the help docs is a barrier
itself. There was a move to improve the help system for Drupal 7 (make
it into plain HTML files), but it didn't get into core.

-- Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Barriers to entry...

2009-11-14T06:52:57Z

Regarding the process and getting non-programmers involved in the help
screens and text in general in Drupal....

For this patch we're working on -- there isn't time to get a new
process in place, because of the time frame. But I agree that there is
a VERY high perceived barrier for non-programmers to help with
documentation in Drupal. This is also a problem for designers who
might want to contribute to themes.

I do have a couple of suggestions for how non-programmers can get
involved and help out with Drupal documentation (more at
http://drupal.org/node/540308):

a) Non-programmers can definitely contribute to the Handbook
documentation on drupal.org. There is a suggested list of ways to
contribute to the Handbook at http://drupal.org/node/302146 and none
of those ideas requires you to "roll patches", work in PHP, etc.

b) If you see problems in the help text or user interface text within
Drupal, you can file an issue. Even if you do not know how to create a
patch, you can still give before/after text suggestions, and someone
else can create the patch. To do that:
- Click on "Create Content" on the sidebar on drupal.org
- Choose "Drupal" as the project
- Choose the Drupal version. Note that for right now, pretty much
only 7.x issues will be addressed -- it is REALLY difficult to get
text changes into 6.x at this point, if not possible.
- Choose component "user interface text" or "documentation", as
appropriate.
- Choose category "bug report" -- text being wrong, missing, or
unclear is a bug, not a feature request or task.
- Make up a clear title and description, and submit your issue.

c) To help with existing issues, search the issue queue for the Drupal
project, component "documentation" or "user interface text" or tag
"Help text" or tag "ui-text". Be aware that most of the issues filed
under component "documentation" are issues with the in-line programmer
API documentation of functions in the source code (displayed on
api.drupal.org), so if you are not a programmer, these will not be
things you will probably want to work on. Even if you cannot write
patches, you can still review patches and make suggestions on how to
improve text, by commenting on issues.

Thoughts?

I was thinking maybe it would be a good idea to propose a session at
DCSF to get non-programmers up to speed on patching, but then I read
one of the commenters saying "no inclination" to learn that...
Definitely, the formatting needed for the help docs is a barrier
itself. There was a move to improve the help system for Drupal 7 (make
it into plain HTML files), but it didn't get into core.

-- Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-14T05:06:42Z

On 11-13-2009 3:11 PM, Lee Hunter wrote:
> Is there any chance that the content development and editing could be
> done via pages on drupal.org <http://drupal.org> and then rolled into
> patches?
>
> There are a lot of people (ok, maybe just me) who could help with
> content but are not down with that whole patch thing. Also it would
> make it a lot easier to compare pages and make sure everything's
> consistent before committing the patches.

I have to agree. There should be an easier way to participate for
non-developers who, like myself, know nothing of CVS systems or patches
or php, and who do not have time or inclination to learn that end of
things, but who (also like myself) might be quite good at helping to
author and organize good help documentation.

I've pretty much given up on helping with docs because I click links
from this discussion list to look at an issue, and then have absolutely
no idea what to do. It looks like I'd have to know php, to know how to
check out items from some repository somewhere (where?), how to write
something called a "patch", how to test it, and so on. This is just not
my profession. The whole approach pretty much freezes just regular old
consultants and writers from your process.

I had done much work on he D7 install guide (the online version) and
therefore offered to also review the install.txt document that gets
included with the downloaded installer , but for some reason this is
much more complicated than just editing a text document. I didn't know
where to get it or what the heck to do with it. I used up my time trying
to figure all that out without ever even finding it.

I will continue to edit any d.o doc pages that I might have priv's to
edit. But I hope some day editing help text is as easy as editing
anything on d.o

kazar

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

Re: Improving help pages in D7

2009-11-13T12:48:38Z

OK, I think the standard has been approved. See
http://drupal.org/node/537828 to sign up for modules to work on.
Thanks in advance for everyone's help!!
--Jennifer

Jennifer Hodgdon wrote:

> Here's a draft standard:
> http://drupal.org/node/632280
>
> Please comment here: http://drupal.org/node/537828
>
> If we get a few more people to review/comment, we can adopt it as a
> standard and move forward with revising the core module help screens
> to conform to our approved standard.
>
> --Jennifer
>

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T12:38:55Z

Lee,

If you have documentation that's ready to roll, send it on to me I'll
be happy to roll patches.

Samir Nassar
612-481-0843
samir.nassar@...

On Fri, Nov 13, 2009 at 2:11 PM, Lee Hunter <lee@...> wrote:

> Is there any chance that the content development and editing could be done
> via pages on drupal.org and then rolled into patches?
>
> There are a lot of people (ok, maybe just me) who could help with content
> but are not down with that whole patch thing. Also it would make it a lot
> easier to compare pages and make sure everything's consistent before
> committing the patches.
>
> Lee
>
>
>
> 2009/11/13 Ariane Khachatourians <arianekhachatourians@...>
>>
>> Sounds good Jennifer -
>>
>> Today is super busy, but I'll try and check in later to review that
>> document. And otherwise I'll be sure to be on IRC lots and will take on a
>> bunch of the rewriting, and maybe I can get a sprint going for the following
>> week.
>>
>> A.
>>
>> On Fri, Nov 13, 2009 at 11:22 AM, Jennifer Hodgdon <yahgrp@...>
>> wrote:
>>>
>>> Arianek and I think there is enough willpower, support, and consensus
>>> to push this forward... I've just updated the original issue to
>>> broaden the scope:
>>> http://drupal.org/node/537828#comment-2262788
>>>
>>> Next step: I'm going to create a draft proposal for the doc standard,
>>> will report back later today on that. Hopefully we can get that
>>> edited/approved, and then we will need to divide up the core modules
>>> and get them conforming to the standard.
>>>
>>> How's that for a plan?
>>>
>>> --Jennifer
>>>
>>> --
>>> Jennifer Hodgdon * Poplar ProductivityWare
>>> www.poplarware.com
>>> Drupal, WordPress, and custom Web programming
>>>
>>> --
>>> 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/
>

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

Re: Improving help pages in D7

2009-11-13T12:26:40Z

Hmmm... That would actually be a pain, given the format that
hook_help() needs for the doc (it has to be translation-ready and
inside PHP strings, etc.). See draft standard at
http://drupal.org/node/632280 for an example of the format that needs
to get into the patch.

I think the main thing to get into this patch is the About and Uses
section headers for each main module help screen. Refining the text on
help pages can be done after the Dec 1st UX deadline, with individual
issues/patches.

--Jennifer

Lee Hunter wrote:
> Is there any chance that the content development and editing could be done
> via pages on drupal.org and then rolled into patches?
>
> There are a lot of people (ok, maybe just me) who could help with content
> but are not down with that whole patch thing. Also it would make it a lot
> easier to compare pages and make sure everything's consistent before
> committing the patches.

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T12:22:58Z

Here's a draft standard:
http://drupal.org/node/632280

Please comment here: http://drupal.org/node/537828

If we get a few more people to review/comment, we can adopt it as a
standard and move forward with revising the core module help screens
to conform to our approved standard.

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T12:11:53Z

Is there any chance that the content development and editing could be done via pages on drupal.org and then rolled into patches?

There are a lot of people (ok, maybe just me) who could help with content but are not down with that whole patch thing. Also it would make it a lot easier to compare pages and make sure everything's consistent before committing the patches.

Lee

2009/11/13 Ariane Khachatourians <arianekhachatourians@...>

Sounds good Jennifer -

Today is super busy, but I'll try and check in later to review that document. And otherwise I'll be sure to be on IRC lots and will take on a bunch of the rewriting, and maybe I can get a sprint going for the following week.

A.

On Fri, Nov 13, 2009 at 11:22 AM, Jennifer Hodgdon <yahgrp@...> wrote:

Arianek and I think there is enough willpower, support, and consensus
to push this forward... I've just updated the original issue to
broaden the scope:
http://drupal.org/node/537828#comment-2262788

Next step: I'm going to create a draft proposal for the doc standard,
will report back later today on that. Hopefully we can get that
edited/approved, and then we will need to divide up the core modules
and get them conforming to the standard.

How's that for a plan?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T11:24:17Z

Sounds good Jennifer -

Today is super busy, but I'll try and check in later to review that document. And otherwise I'll be sure to be on IRC lots and will take on a bunch of the rewriting, and maybe I can get a sprint going for the following week.

A.

On Fri, Nov 13, 2009 at 11:22 AM, Jennifer Hodgdon <yahgrp@...> wrote:

Arianek and I think there is enough willpower, support, and consensus
to push this forward... I've just updated the original issue to
broaden the scope:
http://drupal.org/node/537828#comment-2262788

Next step: I'm going to create a draft proposal for the doc standard,
will report back later today on that. Hopefully we can get that
edited/approved, and then we will need to divide up the core modules
and get them conforming to the standard.

How's that for a plan?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T11:21:57Z

Shari wrote:
> Has there been an issue created for making this standard? So we can see what has
> been discussed, what needs to be ironed out, and what we have?

Arianek and I think there is enough willpower, support, and consensus
to push this forward... I've just updated the original issue to
broaden the scope:
http://drupal.org/node/537828#comment-2262788

Next step: I'm going to create a draft proposal for the doc standard,
will report back later today on that. Hopefully we can get that
edited/approved, and then we will need to divide up the core modules
and get them conforming to the standard.

How's that for a plan?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T10:35:33Z

Has there been an issue created for making this standard? So we can see what has been discussed, what needs to be ironed out, and what we have?
Shari

Jennifer Hodgdon wrote the following, On 11/13/2009 12:07 PM:

bdoesborg@... wrote:

because i volunteered as well (during the paris doc sprints) i pledge
that i write at least 2

we might start off with something simple like the comment module so we
have an example that we can follow


We already have an example: the node module -- see some of the patches 
in http://drupal.org/node/537828

And it looks like we have a few volunteers each willing to take on a 
few modules, so we can probably get it done.

But the next step has to be to write a standard/style guide... I'm not 
sure we have consensus yet that a change needs to be made, or that the 
standard proposed in the patches on that issue is the right one. That 
is what webchick is insisting on, before she'll consider accepting the 
patch. So we have to do that first, or there is no point updating all 
the help files.

    --Jennifer

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

Re: Improving help pages in D7

2009-11-13T10:07:12Z

bdoesborg@... wrote:
> because i volunteered as well (during the paris doc sprints) i pledge
> that i write at least 2
>
> we might start off with something simple like the comment module so we
> have an example that we can follow

We already have an example: the node module -- see some of the patches
in http://drupal.org/node/537828

And it looks like we have a few volunteers each willing to take on a
few modules, so we can probably get it done.

But the next step has to be to write a standard/style guide... I'm not
sure we have consensus yet that a change needs to be made, or that the
standard proposed in the patches on that issue is the right one. That
is what webchick is insisting on, before she'll consider accepting the
patch. So we have to do that first, or there is no point updating all
the help files.

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

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

Re: Improving help pages in D7

2009-11-13T09:53:13Z

because i volunteered as well (during the paris doc sprints) i pledge
that i write at least 2

we might start off with something simple like the comment module so we
have an example that we can follow

boris

2009/11/13 <skessler@...>:

> I am new thro docs team but I can do a module or two.
> Sent on the Sprint® Now Network from my BlackBerry®
>
> -----Original Message-----
> From: Peter Dowling <pwdowling@...>
> Date: Fri, 13 Nov 2009 11:43:44
> To: A list for documentation writers<documentation@...>
> Subject: Re: [documentation] Improving help pages in D7
>
> I had volunteered on that issue I believe.
>
> Yes, I'd be happy to take two or three at least.
>
> - Peter (winston)
>
> On Fri, 2009-11-13 at 08:04 -0800, Jennifer Hodgdon wrote:
>> Hello Drupal Docsters,
>>
>> A couple of months back, arianek noticed some issues in the help text
>> for "node" in Drupal 7, and in conjunction with some other folks and
>> input and such, created a much better version of the help text, with
>> headers, formatting, etc. Issue: http://drupal.org/node/537828
>>
>> The patch was not committed, largely because webchick raised an
>> objection that this would make the help text for the node module quite
>> different from the (rather lame) other help text in Drupal. She
>> basically said she would only commit the improved help page if the doc
>> team committed to improving all the other core Drupal help texts in
>> the same manner. i.e. all or nothing!
>>
>> The deadline for UI text changes is December 1st, which is just 17
>> days away (and several days of that are holidays here in the US), if
>> we wanted to fix up all the help files. There are about 40 core
>> modules that would need this fixup, and one (node) has been done.
>>
>> So, here are the questions:
>>
>> a) Can we come to consensus quickly on a new standard for help docs,
>> and document it somewhere in the Handbook? [Note: I think this doc
>> belongs under: http://drupal.org/node/360052 (Standards, security, and
>> best practices, in the development guide).]
>>
>> b) Can we come up with enough people to divide and conquer the 40 core
>> modules, and rewrite all of their help text to conform to the new
>> standard, and get the patch reviewed, all by December 1st?
>>
>> I'll be on IRC #drupal-doc today as much as I can, if people want to
>> discuss there... or reply to this message.
>>
>> Regards,
>> Jennifer
>>
>
> --
> 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/
>

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

Re: Improving help pages in D7

2009-11-13T09:09:27Z

I am new thro docs team but I can do a module or two.
Sent on the Sprint® Now Network from my BlackBerry®

-----Original Message-----
From: Peter Dowling <pwdowling@...>
Date: Fri, 13 Nov 2009 11:43:44
To: A list for documentation writers<documentation@...>
Subject: Re: [documentation] Improving help pages in D7

I had volunteered on that issue I believe.

Yes, I'd be happy to take two or three at least.

- Peter (winston)

On Fri, 2009-11-13 at 08:04 -0800, Jennifer Hodgdon wrote:

> Hello Drupal Docsters,
>
> A couple of months back, arianek noticed some issues in the help text
> for "node" in Drupal 7, and in conjunction with some other folks and
> input and such, created a much better version of the help text, with
> headers, formatting, etc. Issue: http://drupal.org/node/537828
>
> The patch was not committed, largely because webchick raised an
> objection that this would make the help text for the node module quite
> different from the (rather lame) other help text in Drupal. She
> basically said she would only commit the improved help page if the doc
> team committed to improving all the other core Drupal help texts in
> the same manner. i.e. all or nothing!
>
> The deadline for UI text changes is December 1st, which is just 17
> days away (and several days of that are holidays here in the US), if
> we wanted to fix up all the help files. There are about 40 core
> modules that would need this fixup, and one (node) has been done.
>
> So, here are the questions:
>
> a) Can we come to consensus quickly on a new standard for help docs,
> and document it somewhere in the Handbook? [Note: I think this doc
> belongs under: http://drupal.org/node/360052 (Standards, security, and
> best practices, in the development guide).]
>
> b) Can we come up with enough people to divide and conquer the 40 core
> modules, and rewrite all of their help text to conform to the new
> standard, and get the patch reviewed, all by December 1st?
>
> I'll be on IRC #drupal-doc today as much as I can, if people want to
> discuss there... or reply to this message.
>
> Regards,
> Jennifer
>

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