String freeze: Ensure Drupal 6 module help documentation is accurate and up-to-date

Alright, a status update was requested, and here it is. :)

I've read through and commented on all the documentation. I still need to go through and check the handbook links for all the modules. I should be done very shortly. :)

I do have a couple questions.

1) Should I submit the report as a new issue, or just leave it as a comment here?

2) Would it be OK if I uploaded a .doc file with the comments instead of trying to point them out in plain text? Its easier to show exactly what I'm commenting on in the .doc file. :)

Ok then. Here's a brief synopsis of what I found.

1) Quite a few of the docs had consistency issues. They were mostly between different documents (e.g. tabs the user should click on were italicized one place and quoted in another), but a couple had some problems within the module's text.

2) Several of the docs provided with Drupal were the same as the handbook page (and I think one module was missing any handbook page)

3) The grammar and spelling was excellent. I think I only found two or three of these errors in the whole 17 pages. :)

The actual comments are in the attached .doc file.

Dan

DanW @4: This is very helpful. Thank you for your work on this task. There has been a lot of activity around these help texts recently, and a number of changes to these pages have already been proposed and committed. Reading through your comments, I see other changes [that you note] that need to get into Drupal 6 before the strings are frozen for a release candidate.

The help texts for Aggregator, Locale and Statistics modules are currently various stages of progress in the issue queue. I think Aggregator is RTBC, and Locale and Statistics are awaiting further reviews. If you have any free time and wish to comment on these issues (or others in the documentation component queue), please do so!

Likely outside the scope of this issue, but I note that some of these help texts (block page, menu, for instance) need editing to reflect recent UI improvements, like drag-and-drop ordering.

Unfortunately, I don't have time for a full review of your document tonight (but I will review it tomorrow if no other member of the documentation team has done so).

I've gone back to look at this in more detail, and there are some very valuable comments in here.

I started at the beginning, and went to roll some of them into a 'kitchen-sink' type patch, and then noticed that the version you were reviewing must have been a slightly-outdated snapshot of HEAD, or perhaps even one of the Betas. The help text for the blog module, for instance, was substantially modified by a commit on 11/26. The text in your Word document is from an earlier version. You do have the updated text for some modules, say Blog API, which happened on 11/13. So, your text is from somewhere between the two dates (there are no version numbers in the Word document, so it is difficult to pin down exactly).

That said, however, many of them have not been modified since your copy -- in fact, the vast majority of them are likely just as you reviewed them.

I think you fulfilled the spirit of your task here -- you went through each of the help pages and produced some valuable commentary, much of which can be directly rolled into a patch.

It would be nice, though, if you would go back through and look at the commits that have occurred since your version of Drupal 6 was current, and review the few help pages that have been modified since then. Those could even be submitted as a separate document if that would be easier. I suspect those modules will be Aggregator, Statistics and Blog, but perhaps there were others as well.

In relation to the help text in general, between now and the sometime-soon-string-freeze, hopefully there will be time to:

- create patches for some of the obvious clean-up (small text changes, typos, and the items you mention),
- create patches that make sure the text is synchronized with recent UI improvements, such as a new drag-and-drop interface,
- create patches that help ensure the text of each page is consistent in style and format.

This issue is a big help in doing these three things, and I very much appreciate it!

Edit: test

I used Beta 3, sorry I didn't mention it anywhere.

Since Beta 4 was released today, I can go through those and review the few documents which have likely changed. (or, if I can find out where the very latest commits are, I can go through those as well.)

I'll go update my install now.

Dan

Fantastic!

Have you enabled your Contributor links block on your My Account page? If so, core commit messages ("Core CVS messages") are one of the items in that block (and are at http://drupal.org/project/cvs/3060).

Aha, that would be why I couldn't find the commits. Thanks. :)

I've reviewed the three updated help texts you mentioned earlier (Aggregator, Statistics, and Blog), and can hopefully get any other updated texts done within an hour. :)

Alright, here's the review of all the texts I could find which were different from the ones included in Beta 3. (The only ones that I could find were the ones you mentioned - everything else looked the same)

Also, there's one small issue I noticed (in Beta 4). The link to the "Path" and "PHP Filter" help texts should be switched around to keep all the help links ordered alphabetically.

Dan

Yep.

See, I've read some of those pages a dozen times in the last two or three days and you still find a couple of [now] glaring errors. :)

Thanks! Syncing these last few up with HEAD will make it much easier to roll a quick typo-fix patch for a lot of the items you note. And, I see what you mean about PHP Filter and Path. I guess we should be using a case-insensitive ordering there or something.

This is a task proposed by samtresler, and he or others may have comments they wish to make, but for my part, I think you've done everything asked of you here, plus a little extra for these last three. Thanks for your help! Anytime you want to put your mad English skillz to good use, dig into the documentation component queue!

(webchick, do you want these issues marked RTBC, or can I hijack this issue to roll a patch for some of these suggestions?

Or, alternatively, I guess patching could be a second, follow-up task added to the GHOP queue. Your call.)

DanW: Thank you for going through this! I'm working your suggestions into a patch now, and your work is very helpful.

Unlike poor help.module, which has the most unhelpful help.

There's an actual sentence here which reads:

Modules can make documentation available to other modules with this module.

And like you I'm not sure what "More elaborate help text on sites a module defines" means.

:)

This is such a huge patch, I have to have lots of notes preceding a review:

• DanW: you're the man! It is very doubtful that I would have made it all the way through most of these without having your Word documents as reference.
• I used a Windows/TortoiseCVS system for this instead of my regular system, but I have set everything to Unix EOLs, and the TortoiseCVS patch did apply without problems on linux, so I'm fairly sure the patch is well-formed.
• This is a huge patch, and I'm very sorry about that -- if it is too large to easily review, I'll split it into sections or something. I didn't expect it to be this large when I started, but there were a few things that just had to happen here, IMO.
• That said, I've purposely skipped some very large pages, most notably, menu, locale, block, system and node. There are other issues to handle these (although there are issues that also address some of the items in the patch, as well, though there is not as much duplication here as one might think.)
• In a couple of instances, DanW pointed out where handbook pages did not exist on drupal.org; in the case of PHP Filter module and ... uh... dblog module, I've created a handbook page with duplicate information and left an issue in the documentation queue asking for aliases to be created referencing those pages.
• I've just now finished my first pass through this, and have done little more than apply the patch to a clean installation of head and try out all the help pages to make sure they haven't broken due to a delimiter. I have not read back through this, and it is likely there is more tweaking yet to be done. It is likely I made typos myself as I went through this. :)
• There is a good bit of text changing here, but I feel that it is more than simple mental masturbation. In many instances, these texts were more outdated then I realized: in user module help, we discuss logging in with the [old] drupal module or with a DelphiForumsID (no mention of OpenID). Regardless of whether this exact patch is committed or not or if these exact changes are used, I'm hoping there's sufficient time between now and a release candidate to clean out these [AFAIK] outdated references.
• There was some oddness in an a t substitution in the text for book module (dealing with content types) that I took out, because as nearly as I could determine, it wasn't actually doing anything.
• The help text for help module was so unhelpful, I found it more helpful to delete most of the help. :)
• There are other things left to do on help texts, that hopefully we can leave to another patch (or nine). Namely, in no specific order, (a) take another pass or three through them all, (b) handle node, menu, block, locale, and system (c) make sure that drag-and-drop and other ui changes are reflected, (d) clean up cron language, and (e) standardize on italics/linking conventions.

And, though premature but in case I forget, please be sure to include credit for DanW on [any] commit message.

Huh, big patch. Will try to look through it tomorrow morning with a fresher mind.

Reviewed the help texts modified here:

- the second chunk modified in help module uses @Drupal and @handbook but does not defined them for replacement

- let's roll the locale module changes into http://drupal.org/node/189880 instead, it has some modifications are this region to AFAIR, so why force it for a reroll?

- you add "more help" links in some places, inconsistently... we standardized on "For more information please read the configuration and customization handbook..." in previous releases, but since then the handbook changed, and now this part is named the "Getting started guide" if I see it right. Now that we are adding missing "more help" links, we can just as well fix these. Anyway, this could probably be a follow up patch, but at least try to unify the "more help" text added in this patch.

- "The following types of fields can be added to the user profile:" should say "to the user profiles" not?

- "adjust the indexing behavior" has one too much space

- "The search engine requires a correctly configured system maintenance task" does not look like using the unified 'cron maintenance task'(?) wording and link to the status page.

- the throttle help text seems to loose some of the examples we had there... I see those examples are not extremely good, but it is still good to have some example here, like throttling of blocks which take up lots of resources to fill up with information.

- "The <em>Recent posts</em> page" has one too much space again (this was carried over from before the patch)

- "select the <em>Track</em> option from the user's profile page" uses option, while at other places, we refer to 'tabs', also in this patch

- "<a href="@trigger">Trigger page</a> ." has one too much space

- "users may authenticate" has one too much space

- wow, we are getting rid of the delphiforums reference :) :)

Huh, everything else looks fine.

the second chunk modified in help module uses @Drupal and @handbook but does not defined them for replacement

fixed.

let's roll the locale module changes into http://drupal.org/node/189880 instead, it has some modifications are this region to AFAIR, so why force it for a reroll?

My reasoning was that the http://drupal.org/node/189880 was having to fight through my incompetence to make it to RTBC stage, and I was worried that it might not get in. But, yes, I've deleted the patches to locale.module help here.

you add "more help" links in some places, inconsistently... we standardized on "For more information please read the configuration and customization handbook..." in previous releases, but since then the handbook changed, and now this part is named the "Getting started guide" if I see it right. Now that we are adding missing "more help" links, we can just as well fix these. Anyway, this could probably be a follow up patch, but at least try to unify the "more help" text added in this patch.

Yep. I was trying to do to many things at once. I plan on a patch to remove the "configuration and customization" from that sentence, but that can wait. I've corrected the one for color module. PHP Filter was added, but was already in this format.

"The following types of fields can be added to the user profile:" should say "to the user profiles" not?

How about "The following types of fields can be added to a user profile:" I guess you are technically adding them to all user profiles, though.

"adjust the indexing behavior" has one too much space

- "The search engine requires a correctly configured system maintenance task" does not look like using the unified 'cron maintenance task'(?) wording and link to the status page.

The changes to search module help were somewhat fubared. I've modified them, and added the correct Cron maintenance task items, with links to the status page.

the throttle help text seems to loose some of the examples we had there... I see those examples are not extremely good, but it is still good to have some example here, like throttling of blocks which take up lots of resources to fill up with information.

Good point. I've added back two examples here. (disabling resource intensive blocks and user pictures in posts)

"The Recent posts page" has one too much space again (this was carried over from before the patch)

- "select the Track option from the user's profile page" uses option, while at other places, we refer to 'tabs', also in this patch

- "Trigger page ." has one too much space

- "users may authenticate" has one too much space

Thanks for catching these.

- wow, we are getting rid of the delphiforums reference :) :)

Hehe. Thanks for the detailed review! New patch attached.

Huh, everything else looks fine.

I only had time to look through the first half of the patch but it looks really good. The only thing I didn't like was the parenthetical comment in the color module's help.

The "when using certain themes" part? That can easily come out if you think it would scan better.

The color module allows a site administrator to quickly and easily change the color scheme of the entire site (when using certain themes). 

Parenthetically, I'm fond of parentheticals. :)

Thanks for the update. This looks fine to me, so feel free to RTBC when ready.

Drewish @#22: I redid the first paragraph of color module help to remove the parenthetical:

The color module allows a site administrator to quickly and easily change the color scheme of certain themes. Although all themes do not support color module, both Garland, the default theme, and Minnelli, its fixed width counterpart, were designed to take advantage of its features. By using color module with a compatible theme, you can easily change the color of links, backgrounds, text, and other theme elements. Color module requires that your file download method be set to public.

Thanks for the review and comments, Gábor! I'm hesitant to set this to RTBC myself but I will if nobody else comments soon. Getting this in would allow us to move forward with some of the other patches in the queue.

I went ahead and committed this great patch. If anyone have more to say or corrections to do, they can submit a follow up patch. Thanks DanW, thanks keith.smith!

An academic point, but in the interest of full disclosure, this issue's commit message (Thanks Gábor!) says:

#197297 by DanW (as GHOP 17), and keith.smith: clean up lots of help texts, update to drag and drop functionality, drupal.module removal, etc

Actually, the update to help texts to explain new drag and drop functionality has not happened yet; in fact, this patch largely skips (by design) the large help text blocks of node, block, menu, locale and system, each of which have their own issues.

Quoting myself from #16:

There are other things left to do on help texts, that hopefully we can leave to another patch (or nine). Namely, in no specific order, (a) take another pass or three through them all, (b) handle node, menu, block, locale, and system (c) make sure that drag-and-drop and other ui changes are reflected, (d) clean up cron language, and (e) standardize on italics/linking conventions.

As I read that now, I realize that it was perhaps unclear that items (a) through (e) were not in this patch, but would be proposed for future patches in short order. Many of these are already in the queue, but will need a reroll after this commit. I apologize for any confusion.

@Gábor: not sure if you want follow up patches here or in a new issue. So putting a follow-up here for color.module, happy to move it if you want.

- added (short) third paragraph explaining how to reach the color picker
- made the 2nd sentence of the first paragraph a bit more readable (hope the new parentheses don't cause too many upsets ;-) )

It would be better if you submit another issue to documentation issue queue, unless you have specific comments/issues with the existing patch committed.

Thanks Gábor.

I'm always impressed with how courteous, helpful and patient everyone is round here, especially with those of us who are still learning how the systems operate.

:-)

[See http://drupal.org/node/201437 for the separate issue for color.module documentation improvements]