Help text for core modules - update to conform to new standard

Assigning this to myself.

Here's a first stab at it. Basically replaced "post" with content item and cleaned up the other items identified in the initial issue description.

Version two.

@karschsp as we discussed in IRC I've applied some headings and stripped information on content types. I may have stripped out too much. Comments needed, or please re-roll with updates.

This is a re-roll of arianek's patch with a new heading for "Administering content." I've also attached a screen shot with the output on current HEAD.

To address the extra concerns:
- The list items are all displaying correctly with the revised admin theme. Style would be covered by a different patch anyway.
- the heading, "Node administration pages" is part of the help system and should be covered under a different patch
- the heading, "About" at the top of the page is useful. I'm trying to set up the pages to use a standard set of headings with a final goal that looks like this: http://www.flickr.com/photos/emmajane/3592224815/

The watch worked as described. I think the restructure and wording is a welcomed improvement. Since I am not seeing any items from this issue that this patch does not cover I am marking as reviewed and tested.

Hi,

When I 1st looked at this patch I was torn as to if it should say and/or or not. I have given this a final test and it looks great.

RTBC it is!!!

Very interesting!

So. This represents a MAJOR change to the way this page was before. I think it's a change for the better. However... If we do this here, we need to do it everywhere, both in core, and also in contributed modules. Otherwise, our help pages get totally inconsistent from module to module and that's really bad for user experience.

The last time we did this, the docs team toiled long and hard over a standard that was influenced by real user testing, and generally agreed upon by the community. We rolled it as one ginormous megapatch which made sure that this consistency was kept throughout. I don't recommend doing the "all or nothing" approach again as far as the patch is concerned (although it is AWESOME for bragging rights when you get a 100+ K core patch in ;)), but committing this patch means setting a precedent as well as opening a whole lot of work that needs to be completed prior to RC1 (string freeze).

I would feel an awfully lot better about proceeding in this direction if I could see that there was more high-level discussion, user testing, and general consensus from the community that this new way is truly the way to go. Are there other places where this has been discussed at length and come to a consensus about the way forward? If not, I'm going to need more than 12 replies from a selection of docs team members on some random issue in the issue queue, sorry. :(

It'd help to have a link off to documentation team-wide discussion on the mailing list and/or group, which includes comments from some contributors of some of the best-documented modules, as well as a selection of end-users who have minimal Drupal experience who have recorded their thoughts on "before" and "after".

@webchick Can you please explain the problems that you have with this patch? The headings can be removed from the paragraphs if you feel that is a significant barrier. The structure of the text hasn't actually changed. it's still a one sentence introduction (preceded by the heading, "About") and a short description of the module (preceded by "Use" and including a few sub-headings if relevant). The links are all to d.o and api.d.o "aliased" documentation so that the help text in core can remain brief. If you feel these links are inappropriate, they can also be removed.

I have no problems with this particular patch. I just want to make sure the approach reflects a larger community consensus, especially from the docs team and a few contributed module authors and translators.

What I would've expected is to see along with this patch is a link off to a mailing list, documentation issue queue, or g.d.o discussion where this new direction was discussed at length, pros/cons gone over, and this new formatting being the result that most involved in the discussion deemed was best. But so far, there is only evidence that one person took an initiative, made the judgment call that we ought to make help pages like this, and rolled a patch. That doesn't feel comfortable enough to me to go forward and commit as is, given that it's such a major change from what was there before and is establishing a completely new precedent, and one that will affect every single docs team person working on core, contributed module developer documenting their module, and translator, out there.

I think this direction is definitely favorable, it implies a standard on otherwise very raw sometimes almost article like descriptions. But as webchick mentioned, it does require quite some work - I would like if more documentation team members could provide feedback.

Although I see user testing valuable here, I do not see it as a requirement. Documentation team members, should have enough insight from writing documentation for core and learning from how people use it to make a judgment call here.

Lets not, address the actual help pages beyond just node here - we know the work that needs to be done. This patch should only be used to imply the initial style - where as node is leading for all other pages.

This patch needs a small tweak: the heading for "Theme File(s)" should be "Theme file(s)" (note capitalization) and Handbook Documentation should be Handbook documentation, to be consistent with the rest of Drupal and the rest of that page.

i have been reviewing several help pages today during the doc sprint and i think this is a great improvement because it makes clear *what* information should be on every help page

currently every help page contains different information .e.g. some authors write a lengthy story about user permissions. some don't mention it at all

this improvement would give much more structure on what to write in the help pages,. it also helps reviewing the pages

+1
This is a change for the better. If we could pull this off in some way I'm willing to put in some hours to help this into Drupal 7. And yes I'm the doc team.

Note:
A discussion at documentation sprint at Drupalcon Paris ended up in a number of people agreeing for the adopting the new template for module help pages. All details are not set as to how this will be done, but it might be good to know.

@batigolix and @steinmb and myself were working in docs sprint reviewing many of the help text pages. @dcor was kind enough to lend an ear and review this as well. Adding my voice to those who prefer a format that can more clearly guide what should be on these pages with clear presentation to the user.

From a procedural standpoint to prove that there is bandwidth to get this done would it make sense to file a help text issue with updated text in this fashion for each of the core modules? Once there are a large number of modules covered with patches it might make this an easier call to proceed for @webchick and others interested. And by doing it as separate patches due consideration can be given to each proposal.

It was the opinion of the sprinters working on this today at least that regardless of exact structure many of the core help texts needed at least some review. So +1 for this format, and happy to pitch in with a few of these patches.

If this becomes core standard, then for contrib this merely becomes a template in the contrib module upgrade guide. Since these texts are by design short this should not be onerous.

As discussed at the sprint, here's the node help patch again, but including only the text that must be written. i.e. I've removed the second half of the proposed text which includes links that should be created automatically. I couldn't get the node-help_2.patch to work, so I've rerolled the patch to send it through the testing bot.

This patch has a couple of issues:

1) After applying the patch, I have code that looks like this:

 switch ($path) {
    case 'admin/help#node':
       (etc)
     return $output;
     case 'admin/content':
       return ' '; // Return a non-null value so that the 'more help' link is shown.
      
      return $output;

    case 'admin/content':
      return ' '; // Return a non-null value so that the 'more help' link is shown.

The case 'admin/content' is in there twice, and the second return statement below the first version should be taken out of there too.

2) Generally, lists separated by commas should have a comma before the final "and" (see doc style guide). So:
a) ... manages the creation, editing, deletion, and display of all content on your site.
b) ... including the author, date of creation, and the type of content.

3) A couple of other minor punctuation issues in the "Publishing Content" paragraph:
a) "... records basic information about the content item including the author, date..." -- should there be a comma after item?
b) "... It also tracks the publishing options which define ..." -- definitely need a comma before which
c) "...whether or not the content is: published, promoted to the front page of the site, and/or sticky at the top of content lists." -- I think the colon should be removed here

So, my suggestion for this paragraph would be:

'When new content is created, the node module records basic information about the content item, including the author, date of creation, and the type of content. It also tracks the <em>publishing options</em>, which define whether or not the content is published, promoted to the front page of the site, and/or sticky at the top of content lists. Revision control of content edits is also available. Default settings can be configured for each <a href="@content-type">type of content</a> on your site.'

Here is a new patch. Similar to #24, but fixes the issues identified in #25. Also cleans up a couple of additional spots in node.module where the word "post" is used instead of "content" in doc/UI strings.

Sorry, one typo on there (extra space on a line). Use this version please.

Those two patch files are identical. The test bot must have been having a bad day.

Anyway, I (of course) like the patch (since I wrote the latest version). Maybe someone else can chime in and say it's good, so we can RTBC it?

Hi! I'm a bit anal about the commas - I dunno how big an issue it is - but someone has to say it. That said, reviewed the patch and there seem to be some very minor things that need fixing (i.e. going over the 80 characters in the comment line).

On applying the patch to the latest Drupal7, I found that many of the comment lines in node.module are beyond the 80 character limit.

Otherwise, the patch is sound and works well.

+++ modules/node/node.module	8 Oct 2009 19:13:59 -0000
@@ -80,14 +80,21 @@
+      $output .= '<dd><p>' . t('When new content is created, the node module records basic information about the content item, including the author, date of creation, and the type of content. It also tracks the <em>publishing options</em>, which define whether or not the content is published, promoted to the front page of the site, and/or sticky at the top of content lists. Revision control of content edits is also available. Default settings can be configured for each <a href="@content-type">type of content</a> on your site.', array('@content-type' => url('admin/structure/types'))) . '</p></dd>';

I don't think you need a comma in "about the content item, including the author"

+++ modules/node/node.module	8 Oct 2009 19:13:59 -0000
@@ -80,14 +80,21 @@
-      return ' '; // Return a non-null value so that the 'more help' link is shown.
+       return ' '; // Return a non-null value so that the 'more help' link is shown.

The second line to be added is more than 80 characters. Also, why was this line changed? There are three characters for indentation - should be 2.

+++ modules/node/node.module	8 Oct 2009 19:13:59 -0000
@@ -3042,7 +3049,7 @@
+  $description = $t('If the site is experiencing problems with permissions to content, you may have to rebuild the permissions cache. Rebuilding will remove all privileges to content, and replace them with permissions based on the current modules and settings. Rebuilding may take some time if there is a lot of content or complex permission settings. After rebuilding has completed, content will automatically use the new permissions.');

again, I wouldn't put a comma here... also, "Rebuilding will remove"... could be replaced by "Rebuilding the cache will remove..." to be clearer.

I'm on crack. Are you, too?

I'm being coached on patch review and editing - since this was fairly 'trivial' I had a crack at it. I took out the offending commas (please review) and fixed the 80 character out of limit comment.

So please review so that we can get this patch RTBC... ;)
Cheers!

Good job, dcor!

I think at this point it has had enough reviews. I like it, dcor likes it, ariank likes it, let's commit it.

Hm. So it looks like my comments from earlier still aren't addressed. Or am I to understand that once I commit this patch, there will be a blitz of docs team activity to standardize the remaining core help texts in time for 12/1? As this patch currently stands, it makes node module the oddball one out.

If I understand webchick's objection, it is that this help file uses H3 headers and DL lists, whereas none of the other help files do. Other help files use UL lists (such as forum and block -- at least, they use UL lists), but she's right that this file is visually/layout different from others.

So here is a patch, which retains the textual improvements (such as changing "post" to "content", which has already been decided upon as a standard) and keeps the style as the same, relatively bland style of the rest of the help files in core.

Also that last patch wouldn't apply for me, so this is also a reroll.

I am up for improving all the doc. Addison is busy with real life issues and not participating in doc a lot right now... Maybe we could get webchick, arianek, emmajane, and anyone else who is interested together for a discussion of what needs to be done? I'll post to the doc discussion list...

Screenshot from #11 looks really nice - if any doc team members need help actually rolling patches etc., you'll get plenty of help in #drupal. A lot of changes have been made, to a lot of core modules, which in many cases is likely to have made their help texts inaccurate by now, so would be nice not to ship with completely misleading information.

catch: We are discussing this today on the doc email list and perhaps IRC. The question is whether there are enough people to really get a comprehensive patch together, before the Dec 1st string freeze deadline.

December 1st is UX and performance freeze - i.e. pretty much down to release blockers, but it's not string freeze - that's when the first RC comes out. Because there'll be plenty of critical bugs which require small text changes whilst approaching RC. So while the format ought to be established (and probably most patches rtbc or committed) before December 1st, that's not the hard deadline where there's no further changes to help texts under any circumstances.

Good to know. Anyway, it does sound like we'd need to agree on a format and at least get a patch to update all 40 or so core modules to the new format by Dec 1st, as it's a UX issue.

#drupal-doc to discuss (not that anyone is discussing it there yet, I just proposed it by email on the documentation list this morning)

Key players on the doc team appare to be in agreement now... The plan:
a) I will create (and post here a link) a draft standard for help files, based on what we all agreed was a good format (patch in #32).
b) We'll review/approve the standard.
c) Once that's approved we have a team of volunteers who are willing to each update a couple of core modules to conform to the standard. Must get this patch in by Dec 1st as it's a UX change. But we can still make some changes to the text in the help files after that, if we need to until string freeze (which comes later).

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

By the way, it's a slight change from the patch proposed in #32 -- I took out the P tags within the DL tags (seemed unnecessary to me).

The draft looks easy to implement. Looks good to me. Let's get this in.

I'm going to declare the standard approved, since many folks liked the patches above, and at least three of us have commented here (including myself) that they like the new standard.

Next step: Create patches for core modules. We already (mostly) have one for the node module.
Anyone who wants to help:

a) Choose a few core D7 modules to work on, and comment here on which ones you are claiming. Don't choose the node module, as it's more or less done. I will make a list and edit who is claiming each one as we go (next comment, coming shortly).

b) Make a patch for your set of modules, conforming to the new standard in http://drupal.org/node/632280, with appropriate updates (especially check the paths to the module's screen, as many of them have changed). If you need help with the patching process, please join #drupal-docs on IRC and we'll get you going. Or on #drupal, but #drupal-docs tends to be smaller/friendlier. :)
c) Attach your patch (if possible, combine several modules into one patch). Leave the issue status as "needs work". If you decide not to complete the modules you claimed, please comment here.
d) Once we have all the patches, I will roll them into one big patch and mark issue "needs review" so we can get this in.

c) New process: Create a new issue and attach your patch there. The new issue should have:
Project: Drupal
Version: 7.x
Component: documentation
Category: bug report
Status: Needs review
Title: "Help File Fixup: [names of modules you are patching]"
Body: Make sure to link back to this issue. The best way to put in a link is to put [#######] in the body of your message, replacing ##### with this issue number, which is 537828. That makes it turn into a link that shows the issue name, like #537828: Help text for core modules - update to conform to new standard.
Tags: Add tag "d7help" to your issue

d) Add a comment to this issue, with a link to your new issue (same way, [######]).

e) Here's a list of all the tagged d7help issues, if you want to review patches:
http://drupal.org/project/issues/search/drupal?order=last_comment_timest...

How's that for a plan?

List of core modules that presumably need patching -- comment here to claim a group of them (especially if you have a lot of knowlege about a particular module, but even if you don't, you can at least get the headings in there and verify the paths):

NOTE: Check somewhere after comment #126 - probably this comment has been superceded by a new comment that will monitor status, edited by arianek!!!!!

If someone has claimed a module, their user name will be listed here - have edited this to reflect claims through comment #126 so far.
If someone has done at least a first version of a patch for the module, it will have a link to the new issue where the patch is.

aggregator - #633312: Help File Fixup: aggregator
block - #632898: Help File Fixup: Block module
blog - #633064: Help File Fixup: Blog Module
book - #633134: Help File Fixup: Book Module
color - #633654: Help File Fixup: Color Module
comment - #633750: Help File Fixup: Comment module
contact - samirnassar
dashboard - #637710: Help file fixup: poll and dashboard
dblog - #635282: Help File Fixup: dblog, php, rdf
field and field/modules/* sub-modules - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
field_ui - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
file - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
filter - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
forum - #632996: Help File Fixup: forum
help - #633812: Help File Fixup: Statistics module
image - #633808: Help File Fixup: Image module
locale - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
menu - #634820: Help File Fixup: Menu module
node - #632820: Documentation standard update : node.module
openid - samirnassar
overlay - OMIT - this appears to be an empty shell and not really a module
path - shai
php - #635282: Help File Fixup: dblog, php, rdf
poll - #637710: Help file fixup: poll and dashboard
profile - #635056: Help Text Fix-up for Profile Module
rdf - #635282: Help File Fixup: dblog, php, rdf
search - #633346: Help File Fixup: search
shortcut - #636822: Help File Fixup: shortcut and toolbar
simpletest - #634234: Help File Fixup: system, syslog, and simpletest
statistics - #633812: Help File Fixup: Statistics module
syslog - #634234: Help File Fixup: system, syslog, and simpletest
system - #634234: Help File Fixup: system, syslog, and simpletest
taxonomy - bangpound
toolbar - #637710: Help file fixup: poll and dashboard
tracker - #635900: Help File Fixup: Tracker module
translation - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
trigger - #632716: Help File Fixup: field*, file, filter, locale, translation, trigger
update - denverdataman
upload - samirnassar
user - #633616: Help file fixup : user.module

I can take care of:
trigger
field
field/modules/*
filter
translation
file
node

Subscribing / volunteering / will really try and find some time to help out next week

I can take:

user
upload
openid
contact

As a starter snack.

great! I have these listed as claimed in #49. Going out for a few hours, so apologies if future claims don't make the list right away.

I'll also re-roll the node module patch to strip the p elements out.

bangpound: I have a busy weekend, not likely to be in IRC then, sorry!

I can take forum.

I'll take...

dblog
path
poll
php
tracker

Sounds good. I am starting on my list... Found a few that only really merited "About" section, not "Uses"...

I will take update as my first patch and then if there is a need I will take on something else. Is there a good place on how to write a patch verses just the content.

Thanks,
Steve

denverdataman: Do you have CVS installed?

Just a note: We need to update this section of the handbook to conform with new standards: http://drupal.org/about/authoring/writing

In spite of the URL, this is the section on writing embedded documentation in modules.

denverdataman: Here is the handbook section on creating patches: http://drupal.org/patch

OK, here is my patch for the modules I spoke up for (plus a few more that I added silently to my list - the privs of the list manager :) ).

Just a note, if this standard is agreed, I'd really recommend separate issues for modules (or possibly groups of modules) to keep the patches a reviewable size, then linked from here. 45k is fine, but once they get to 70k/80k reviewing and re-rolling gets a lot harder.

Here's a screen shot of the Filter module help page, using the new format.

denverdataman: If you are not comfortable/able to make a patch, you can paste your suggested version of the hook_help() implementation in a comment here. If you enclose it in <code> </code> it will format properly and someone else can create a patch. Thanks for being willing to help in any capacity!!

Sorry I'm late to the party. Great going. I'll commit to doing three. I'm on an iPhone now so I won't try to sort out what isn't taken at the moment. Will be back online in Sunday.

One thing on the standard... I think that when we refer to admin pages we should print the Drupal path to the screen and not hide it behind the link text. I think the Drupal path should be the link text. I don't know if it is too late to address the standard on this point.

Another concern. I think the php, heck even the HTML is a real distraction in what is, essentially, a writing task and not a coding task. Actually that is wrong, it is both. But I think we'll be more welcoming to writers and better able to incorporate feedback on the writing if the writing it
is done first and not in code. Once there is sign-off on the text, it can be converted to code.

In line with Catch's concerns, I think individual wiki pages for each module on groups.drupal.org would be best for writing. After it is written and reviewed in English on g.d.o then it can be converted to code and the patch rolled and submitted as it's own issue on the project/drupal issue queue.

Is the docs group at g.d.o still read only?

In addition to volunteering to write the help text for 3 modules... If we are able to create wiki pages at g.d.o. I'd be happy to review a bunch over there.

I hope this doesn't sound like I'm throwing a wrench in. This energy is awesome.

Shai

Wow, holy cow! So glad to see such a flurry of activity around this great initiative! :D

Yes, catch is right that either each module or else "chunks" of modules in their own separate issues will probably make more sense here, esp. if we have this many people helping. You don't want to be halfway through rolling a 80K patch when someone else posts a new text. :\

So maybe we can use this issue as sort of a "meta" collaboration point and then link off to sub-issues with the actual fixes in. Once they're reviewed by at least one other person who did not work on changing the text itself, go ahead and mark to RTBC. I'd like to get these in quickly when we start rolling with things.

I think rolling a massive patch is a bad idea. A massive patch would likely cause a vast majority of rtbc and under review patches to need to be re-rolled. Unless the idea would be that the big help patch would be the last patch to go in, in which case the help patch team would have to keep re-rolling the behemoth as other patches are committed. The word is "patch" for a good reason!

Leaving aside the question as to whether we could/should do wikis for writing the help text, for committing, I think the best workflow would be for the person writing module help text to submit a new issue to the project/drupal queue either module-by-module or for a few modules. And we should pick a tag for this work.

And people signing up to write the help should know that they don't need to do the coding or patch rolling in order to write the help text and start the issue in the queue. They shouldn't start an issue, however, for a module they haven't spoken for.

Shai

@webchick Agreed, I will help with turning this into a [meta] collaboration issue. I will be distant from, creating/changing actual text - so I can review and possibly mark RTBC.

I'm working on the module "Statistics"

did "statistics". i will continue with "image"

please update #49

delete this comment please

My patch in #66 has been moved to a new issue: #632716: Help File Fixup: field*, file, filter, locale, translation, trigger.

I'll edit the meta-comments #48 and #49 above with the new suggestion (file a new issue with your patch).

batigolix and arianek: In accordance with new process, please file separate issues with your patches, and make a link/comment here. See revised #48 above. Thanks!

arianek: I like your patch just fine, please go ahead and file an issue.

And batigolix: I don't think we can completely delete comments that have been previously submitted, as it would screw up the numbering and people are always referring to "#23 above" etc.

THANKS everyone who is helping with this!!!!

My next batch of modules to claim:
simpletest
system
syslog

Node module help text cleaned up and re-rolled against CVS update #632820: Documentation standard update : node.module

Here's the forum one: #632996: Help File Fixup: forum

I'll do

1. color
2. profile

shai

This is fun! Claiming aggregator and search.

The following appear to not have a hook_help call (aka hook_helpless :):
RDF
dashboard
overlay (doesn't include .module file either)
shortcut
toolbar

Great progress!

I've updated the instructions in #48 above to include the d7help tag, and updated the module list in #49 above with all the changes up through #90.

JuliaKM - regarding those modules that currently lack hook_help() -- I think all core modules should have hook_help(). But if there is no .module file, then maybe not, though we could make one just to have a hook_help(). It seems to me that any core module should at least have an "About" text? Thoughts?

And here's a link to search for all issues tagged with the new d7help tag, if you want to review:
http://drupal.org/project/issues/search/drupal?order=last_comment_timest...

Here's the aggregator issue: #633312: Help File Fixup: aggregator
And, here's the search one: #633346: Help File Fixup: search

jhodgdon: I think that all of those modules are new in Drupal 7 and that might be the cause of the missing documentation. In the case of overlay, I didn't find any hook_help in this patch. Should we create a separate group ticket to write hook_help documentation for RDF, dashboard, overlay, shortcut, and toolbar? I'm not sure what the protocol is but I agree that it seems like they should have hook_help documentation. We might want to wait to work on overlay until it has more than a .info file.

JuiaKM: My patch for the field modules added help to 3 modules that previously had none... I think it can be done under this issue umbrella, since I think our standard is that every core module should have an About page. :) But let's leave Overlay for last. :)

#633616: Help file fixup : user.module first draft posted.

I've updated text and written a patch for the color module. Here is the issue, it is awaiting review: http://drupal.org/node/633654

Shai

help text image module issue: http://drupal.org/node/633808

help text statistics module issue: http://drupal.org/node/633812

here is the issue for rewriting the help text of the "HELP" module

http://drupal.org/node/633836

(yes, i will not try to get confused)

please update #49 so that I can see what modules still need to be done

if necessary: redistribute the modules that are "claimed" by others but havent started yet

yeh! i'm comment #100!

#49 has been updated. I think we can give people who claimed modules to do a couple of days to complete them before deciding they aren't going to finish, but if anyone has realized they don't have time, please let us know, since we have others clamoring to finish more modules!

:)

System, syslog, and simpletest have been revised:
#634234: Help File Fixup: system, syslog, and simpletest

I have a question about the standard...

It seems that everyone is pulling out <h3>, <p>, <dl>, <dt>, and <dd> from the t function. But nobody seems to be pulling out <a> and <em>. Is there a logic to that?

Shai

Shai:

Yes, there is a logic to it... Each call to t() needs to contain a complete piece of text (sentence, paragraph, etc. in this case), because each call to t() results in one piece of text to be translated. Different languages have completely different word order for sentences, so if you did something like:

t('For more information, see the ') . '<a href="whatever">' . t('abc page') . '</a>.'

it would not necessarily work when it was pasted all back together after translating the two fragments separately, for all languages. You need to have the whole thing in one call to t() so that the whole thing is translated as one string, and different languages can reorder as necessary. Same with EM elements when they are highlighting one or two words within a sentence.

Jennifer,

Got it. Thanks for explaining. That makes sense.

Shai

I had hoped to have time last weekend to do these, but that didn't work out. So I'll put these back in the pool if anyone wants to jump on them...

dblog
path
poll
php
tracker

I'll check back in this weekend and if any are still to do will try to take one then. Will also try to check back in to review others that have been posted.

Hey folks,

I'm doing the re-format/re-write for Profile module. Given that Profile was slated for a big change that didn't happen, but surely will happen for D8... I'm a bit stuck. Can anyone address these questions, give some guidance, send me in the right direction?

Here are some questions:

1. Is there anything about Profile module's limbo-ness that needs to go on the help page now for D7? Open source process should be transparent. I don't think we should hide the fact that this module is on its death bed, even as we ship out a brand new version. Microsoft wouldn't do that; but we aren't Microsoft, for a reason.
2. For folks building new sites (as opposed to upgrading from D6), should they be encouraged to attach (CCK) Fields to users as a better practice than using Profile module's special and certainly-by-d8-to-be-dead fields?
3. Can we trust an upgrade path in the future out of Profile will be rock-solid or is it preventative maintenance to use (CCK) Fields instead now?

Shai

In #106 Winston put a few modules back in the pool (I see they are swimming quite nicely ;->).

I will pick up path.module.

So Jennifer, when you get, to it, you can replace "winston" with "Shai" in #49 re: path. @jhodgdon, thank you for being our leader!

Shai

Gang, anyone interested in addressing the questions I asked in #109 about how to approach the help-text fix-up for Profile module, should do so at the following issue I've established:

http://drupal.org/node/635056

Shai

Smart, Shai, to move that to its own issue! I've added a comment there.

Anyway, I think the module status post #49 is updated to this point now. Some of you must be in time zones or on schedules other than mine (for instance, I know arianek is in my time zone, but I sure wasn't awake when she posted that last patch!) :)

So: I'll take dblog this morning, and rdf and php.

im fishing "Tracker" out of the pool

New issue for the dblog, rdf, and php modules: #635282: Help File Fixup: dblog, php, rdf

Wow, looks like we only have 4 unclaimed modules! Great work folks!!

"tracker" done: http://drupal.org/node/635900

is everybody trying to dodge the "shortcut" module ? :)

I just took a first pass at shortcut but it's not pretty. Please make it sound better, #636822: Help File Fixup: shortcut and toolbar

I don't feel strongly that we need the link on all modules -- some of them may not have handbook pages, and some of the handbook pages don't really say anything useful.

And I don't feel strongly that it belongs in About or Uses. I think it depends on what the Handbook page says. If the Handbook page gives "about" information, put the link in About. If it has information on how to use the module, put it in "uses". If it doesn't say anything too usefull, omit the link.

That's my opinion, anyone else?

I think Jennifer(@jhodgdon)'s approach makes a lot of sense.

Shai

(ignore me; just tagging as one of the important issues to focus on for D7 UX freeze. keep up the great work!)

regarding #120: most handbook pages i've seen repeat the ("our") help texts and elaborate further on that. so the handbook page is "about" and explains "uses"

So, if you think that linking to the Handbook makes sense for a particular module, put the link where it makes sense. We could add that as a standard on http://drupal.org/node/632280, but it's not much of a standard...

OK, I have some more time this morning, so I'll take on the rest of the uncommitted modules: dashboard, poll, and toolbar.

those three are ready for review:
#637710: Help file fixup: poll and dashboard

So, it looks like all the modules have now been claimed, and most have been either patched or at least issues have been started. Great work!

The remaining unpatched issues are claimed by:
samirnassar (contact, openid, upload), shai (path), bangpound (taxonomy)

If you do not plan to finish these soon, please comment here and someone else can take them on. If they are not done by Saturday evening (West coast USA time), we've decided that they are fair game for anyone else to claim on Sunday.

Also, arianek will be taking over the oversight of this issue this weekend, as I'm out of town next weekend. And neither of us is available much this weekend... but don't let that stop you! :)

Hey all! arianek is taking over monitoring this issue for the next week (I'll be traveling). Thanks arianek!

Most of the modules have at least a first patch. Reviews are requested. Here's a link that shows all the tagged issues:
http://drupal.org/project/issues/search/drupal?order=last_comment_timest...

i hunted, poached, caught, killed, skinned, butchered and cooked (to stay in the metaphor) Path module:

#639738: Help File Fixup: Path module

opened the hunt for the upload module

caught, killed, butchered, fried and ate Upload module (hold on to the metaphor, people) :

#639950: Help File Fixup: Upload Module

Keep up the great work, folks! Several of those patches have been committed, others are awaiting review... I'm out in Georgia now, and will probably have some time in the mornings to do some reviewing, patching, etc. (the people I'm visiting are not big on mornings).

arrrr. taxonomy

ok . ill give it a shot

caught killed cooked taxo help: #640348: Help File Fixup: Taxonomy module

I did a bunch of reviews this morning... :)

Anyone else wanting to review or re-roll patches, please see: http://drupal.org/project/issues/search/drupal?issue_tags=d7help

Hopefully all the issues are tagged properly.

There's some confusion now about the standards for capitalizatio.

By my understanding, the UX team approved the ideas in http://drupal.org/node/632280 as they are currently. Which is to say, the About starts with "The node module", not "The Node module".

Can someone who is working this week please confer with the UX people and find out if this was intentional or an oversight? The node patch went in this way, but the next three patches that went in (block, aggregator, and something else I can't recall right now) had the second convention. And there are a LOT of patches about to be RTBCd and committed. I'd prefer to get the standard straight now rather than having to go patch them all again...

Just as a note, prior versions of Drupal had the module names not capitalized in the help screens. Not saying I agree with that standard, but that was the de facto standard.

I will try to find usability folks in IRC now and report back.

I've asked on #drupal-usability for someone to comment here. If they don't have an opinion, then the doc team can decide on a standard (quickly) and change the standards page if needed. And then change existing patches if needed. Several will need to be redone in either case.

I have to go now... I don't have a strong opinion either way, but I would like to see consistency and to have a standard.

I'm not on the UX team, but as an English nerd, I think that they should be capitalized. They're capitalized in the modules interface, so users will expect that. In fact, I'm 99% sure that the reason they're not capitalized in the current help text is probably because this text was written in Drupal 4.7 era, before we had .info files, so all modules were indeed lowercased back then.

+1 for matching the modules UI, and capitalizing module names consistently.

I dont think we made any official call on this, it seems normal grammar applies - a name should be capitalized?

+1 for capitalizing the module names. It seems to me they are a proper noun.

Bojhan is on the UX team, so if he says it is OK, it is probably OK. Plus, we have consensus. Let's change the standard and get those patches in. And ignore all my "needs work" comments based on this standard. :)

I've edited the standard page to say the name of the module should be capitalized, and also updated the example there.
http://drupal.org/node/632280

Now to find all those issues and mark RTBC instead of needs work.

Looks like all of them are updated now... Anyway... If we can get a bunch of these patches in, it might be good for us all to take a quick look at the final result (all the help screens) and proofread before 12/1. Whew!

I marked node "needs work". No need for mental notes when we have an issue queue. :)

so?
we will fix m all before dec 1?
maybe a new call for action via the email distri list?

This may need some work but I am getting bogged down trying to write the PHP.

On file \modules\update\update.modules

Line 80

return '<p>' . t('Here you can find information about available updates for your installed modules and themes. <br />Note: Modules and themes are part of projects that can have different names than their module(s) and theme(s). Some modules or themes will also have multiple modules or themes as part of their project. You can find a list of projects on <a href="http://www.drupal.org/project" target="_blank">Drupal.org</a>') . '</p>';

This new code replaces lines 112-113

+      $output = '<h3>' . t('About') . '</h3>';
+ $output = '<p>' . t("The Update manager periodically checks for new versions of your site's software (including contributed modules and themes), and alerts administrators to available updates.") . '</p>';
+      $output .= '<h3>' . t('Uses') . '</h3>';
+      $output .= '<dl>';
+      $output .= '<dt>' . t('Update reports') . '</dt>';
+      $output .= '<dd><p>' . t('The <a href="@update-report">report of available updates</a> will alert you when new releases are available for download. If <a href="@update-settings">configured</a> Update manager will send an email to one or more addresses with update notifications.', array('@update-report' => url('admin/reports/status'), '@update-settings' => url('admin/reports/updates/settings'))) . '</p></dd>';
+     $output .= '</dl>';
+      $output .= '<h3>' . t('Administering updates') . '</h3>';
+      $output .= '<dl>';
+      $output .= '<dt>' . t('Update reports') . '</dt>';
+      $output .= '<dd><p>' . t('You may configure options for update checking frequency and notifications at the <a href="@update-settings">Update manager module settings page</a>. You will also need to configure when cron jobs are ran which will determine when updates reports are generated', array('@update-report' => url('admin/reports/status'), '@update-settings' => url('admin/reports/updates/settings'))) . '</p></dd>';
+      $output .= '<h3>' . t('Handbook Documentation') . '</h3>';
+      $output .= '<ul><li>' . t('<a href="@handbook-update">Update manager module</a>', array('@update' => 'http://drupal.org/handbook/modules/update'')) . '</li></ul>';
+     $output .= '</dl>';
      

Ok, my queue is now empty again. More patches plz! Looks like we're about halfway done! YEAH! :D

I updated #132 with some of the updates within the past few days.

another 10 something patches queued

I am trying to get "The XX module" out of core, because people don't say "The Dries developer" or "The Volkswagen car" either. Modules have names; we should use them directly. It just sounds weird and unprofessional.

I don't agree that it sounds weird or unprofessional to say "The Abc module allows you to...".

We had a handbook page from a couple of months ago discouraging this style which bergco worked on as well. Unfortunately it seems to have been removed.

Xano: Sorry, what? That makes no sense. Volkswagen is not a word used in normal every-day usage, so there is no need to qualify it with "car." On the other hand, Contact, Image, File, and Toolbar are all every day words, used in multiple contexts. It totally makes sense to qualify them with "module" when we're referring to the module.

If you want to help this initiative, please review patches rather than trying to change specs at the last second.

Here, let's do this. ;)

Every issue on http://drupal.org/project/issues/search/drupal?issue_tags=d7help is now RTBC or fixed. :)

I am thrilled to report that http://drupal.org/node/537828#comment-2294410 is now a SEA of green! Yes, that's right! An entire SEA of it!

There are just two stragglers, both related:

#645776: Help File Fixup: field
#645802: Help File Fixup: File module

...and... there may have been some patches committed in the past few days which added modules and did not take this new standard into account... gulp!

#653000: Create help page for Overlay module following new standard
#653004: Create help page for Contextual module following new standard

Please direct all hate-mail to:

Angie "webchick" Byron
123 I'm Really Sorry Lane
Don't Shoot Me, PLZ
10101010

If it helps, ummm... we deleted Upload module? Eh? Eh?? :\

(Note: I do not have any more "new module" patches on my radar, so this should be the last of them.)

I'll see if I can beat you to them. :)

We are down to just 3 issues, all of which are in RTBC status!

BOOM!

All of these issues have been COMMITTED TO HEAD!

Great work, everyone!! :D This was a huge achievement, and I love how you all banded together and got this done. Thanks SO much!