/admin/help/node text needs a little rewrite/review work - obvious issues:

- First sentence has a space before the period.
- It appears that "story" is being changed to "article" in D7, if so that will need updating as well.

Files: 
CommentFileSizeAuthor
#171 blank.patch0 byteswebchick
Passed on all environments.
[ View ]
#77 help_statistics_1.patch8.47 KBbatigolix
Unable to apply patch help_statistics_1.patch
[ View ]
#77 help_statistics_before.png95.66 KBbatigolix
#77 help_statistics_after.png88.69 KBbatigolix
#72 help_block.patch4.8 KBarianek
Unable to apply patch help_block_1.patch
[ View ]
#72 help_block_before.png109.85 KBarianek
#72 help_block_after.png92.06 KBarianek
#68 filterhelp.jpg106.99 KBjhodgdon
#66 537828-jhodgdon.patch45.34 KBjhodgdon
Unable to apply patch 537828-jhodgdon.patch
[ View ]
#35 537828.patch7.4 KBjhodgdon
Passed: 14732 passes, 0 fails, 0 exceptions
[ View ]
#32 537828_new_2.patch7.2 KBdcor
Passed: 14681 passes, 0 fails, 0 exceptions
[ View ]
#29 537828_new.patch7.37 KBarianek
Passed: 14693 passes, 0 fails, 0 exceptions
[ View ]
#27 537828.patch7.37 KBjhodgdon
Failed: 13255 passes, 1 fail, 0 exceptions
[ View ]
#26 537828.patch7.39 KBjhodgdon
Passed: 14686 passes, 0 fails, 0 exceptions
[ View ]
#24 node-help_3.patch4.02 KBemmajane
Passed: 14723 passes, 0 fails, 0 exceptions
[ View ]
#11 node-help-after2.png68.3 KBarianek
#11 node-help_2.patch4.66 KBarianek
Failed: Failed to apply patch.
[ View ]
#9 node-help.png47.31 KBemmajane
#9 node-help.patch4.66 KBemmajane
Failed: Failed to apply patch.
[ View ]
#7 node-help-orig.png126.31 KBarianek
#7 node-help-before.png114.49 KBarianek
#7 node-help-after.png122.94 KBarianek
#7 node-help.patch4.74 KBarianek
Failed: Failed to apply patch.
[ View ]
#5 node-help.patch4.51 KBemmajane
Failed: Failed to apply patch.
[ View ]
#4 node.help_.000.patch3.7 KBkarschsp
Failed: Failed to apply patch.
[ View ]

Comments

arianek’s picture

Assigned:arianek» Unassigned

unassigning this from myself, as there's not much use attempting to review/edit until more clarification on the use of the word "post" (http://drupal.org/node/523244#comment-1880448 Bojhan says it's not to be used anymore). may pick it up again later on...

arianek’s picture

Status:Active» Needs work
Issue tags:+d7docs
emmajane’s picture

Assigned:Unassigned» emmajane

Assigning this to myself.

karschsp’s picture

Status:Needs work» Needs review
StatusFileSize
new3.7 KB
Failed: Failed to apply patch.
[ View ]

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.

emmajane’s picture

Assigned:emmajane» Unassigned
StatusFileSize
new4.51 KB
Failed: Failed to apply patch.
[ View ]

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.

Status:Needs review» Needs work

The last submitted patch failed testing.

arianek’s picture

StatusFileSize
new4.74 KB
Failed: Failed to apply patch.
[ View ]
new122.94 KB
new114.49 KB
new126.31 KB

ok, I made some very small changes to the h3 sub headings, a couple small changes to the text in the "user permissions" section, and fixed the list styles for "theme files", "development", and "handbook documentation".

things that still don't seem quite right to me:

- "The administrative content page allows you to review and manage your site content." doesn't seem to belong under "user permissions" but i don't know where to put it
- the heading "Node administration pages" needs all first letters capitalized according to the doc style guide (i don't know where this section of code is!)
- also in this section, the bullet type doesn't match the rest (again, don't know where the code is)
- the title "about" under the main heading seems unnecessary - can we remove it? (i think it's fair to assume the first para under the title is a general intro or about text).

based on talking to emmajane on IRC it seems like we want to be able to make the format consistent on these help pages, so i'm wondering if there would be any point in putting some id's on each header that will be consistently on there? i don't totally understand PHP enough to guess how we might plan ahead for a help module.

oh and ps. i am really uncertain about those list styles, i have a feeling they're not coded properly to add more list items ???

screenshots:
orig = pre emma's patch
before = emma's patch version
after = new patch applied

also, the new patch was diff'ed from root

arianek’s picture

Status:Needs work» Needs review
emmajane’s picture

StatusFileSize
new4.66 KB
Failed: Failed to apply patch.
[ View ]
new47.31 KB

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/

ano1’s picture

Status:Needs review» Reviewed & tested by the community

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.

arianek’s picture

Status:Reviewed & tested by the community» Needs review
StatusFileSize
new4.66 KB
Failed: Failed to apply patch.
[ View ]
new68.3 KB

Cool that all looks/sounds great to me, cept I made one small change in the text of the Uses: Publishing Content section, changed "and is sticky..." to "and/or sticky..." otherwise big thumbs up.

Can someone give this patch one final test and then re-mark as RTBC?

ano1’s picture

Status:Needs review» Reviewed & tested by the community

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

webchick’s picture

Status:Reviewed & tested by the community» Needs review

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

emmajane’s picture

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

webchick’s picture

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.

Bojhan’s picture

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.

jhodgdon’s picture

Status:Needs review» Needs work

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.

arianek’s picture

@jhodgdon the handbook says all initial caps - there's a discrepancy somewhere between styles for docs and styles for api/code i think http://drupal.org/node/338208#headings

jhodgdon’s picture

Issue tags:-help system+Help text
batigolix’s picture

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

steinmb’s picture

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

dcor’s picture

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.

winston’s picture

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

emmajane’s picture

Status:Needs work» Needs review
StatusFileSize
new4.02 KB
Passed: 14723 passes, 0 fails, 0 exceptions
[ View ]

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.

jhodgdon’s picture

Status:Needs review» Needs work

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.'
jhodgdon’s picture

Title:Text on help page for "node" needs updating» Help text for "node" needs updating
Status:Needs work» Needs review
StatusFileSize
new7.39 KB
Passed: 14686 passes, 0 fails, 0 exceptions
[ View ]

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.

jhodgdon’s picture

StatusFileSize
new7.37 KB
Failed: 13255 passes, 1 fail, 0 exceptions
[ View ]

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

Status:Needs review» Needs work

The last submitted patch failed testing.

arianek’s picture

Status:Needs work» Needs review
StatusFileSize
new7.37 KB
Passed: 14693 passes, 0 fails, 0 exceptions
[ View ]

skimmed the patch, looks good to me - reroll for the testbot.

jhodgdon’s picture

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?

dcor’s picture

Status:Needs review» Needs work

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?

dcor’s picture

Status:Needs work» Needs review
StatusFileSize
new7.2 KB
Passed: 14681 passes, 0 fails, 0 exceptions
[ View ]

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!

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

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.

webchick’s picture

Status:Reviewed & tested by the community» Needs review

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.

jhodgdon’s picture

StatusFileSize
new7.4 KB
Passed: 14732 passes, 0 fails, 0 exceptions
[ View ]

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.

arianek’s picture

So... is there a good reason we don't actually address what @webchick is saying and make a proper decision either to use this nicer, more consistent format for all the core help text, or to shelf it? This certainly isn't the only one that needs work. (Seriously, just look at /admin/help/profile ...eeek.)

Personally, I think (as many of the others have mentioned) that it's a huge and worthwhile improvement to the current state of the help text, much of which at least needs to be updated to match D7 anyway.

December 1 though, hey? Admittedly that's pretty tight. Anyone know if this is on Addi's radar at all or if we need her blessing?

There are 35 core help texts to clean up. I can't do the PHP changes, but if someone can do the main modifications to the structure, and help adding the links in properly, I'd be up for working on breaking up the current text accordingly - and hopefully getting a bunch of major editing/rewriting done as well. I don't think I can handle the whole lot on my own, but I could probably get through about 10 of them?

What say ye @jhodgdon @emmajane et al?

arianek’s picture

duplicate comment

jhodgdon’s picture

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

catch’s picture

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.

jhodgdon’s picture

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.

catch’s picture

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.

jhodgdon’s picture

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)

jhodgdon’s picture

Title:Help text for "node" needs updating» Help text for core modules needs standard, updates
Status:Needs review» Needs work

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

jhodgdon’s picture

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

arianek’s picture

Just reviewed @jhodgdon's draft for standards based on the node help patch. Looks good to me, as far as using it as a template for the rest of the help updates.

jhodgdon’s picture

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

samirnassar’s picture

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

jhodgdon’s picture

Title:Help text for core modules - update to conform to new standard» Help text for core modules needs standard, updates
Issue tags:-d7help

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?

jhodgdon’s picture

Title:Help text for core modules - update to conform to new standard» Help text for core modules needs standard, updates
Issue tags:-D7 UX freeze, -d7help

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

jhodgdon’s picture

Title:Help text for core modules needs standard, updates» Help text for core modules - update to conform to new standard
jhodgdon’s picture

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

arianek’s picture

DIBS: block, blog, book, and comment to get started.

prbass’s picture

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

samirnassar’s picture

I can take:

user
upload
openid
contact

As a starter snack.

bangpound’s picture

I can help with taxonomy. See you in IRC on the weekend?

jhodgdon’s picture

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.

samirnassar’s picture

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

jhodgdon’s picture

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

JuliaKM’s picture

I can take forum.

winston’s picture

I'll take...

dblog
path
poll
php
tracker

jhodgdon’s picture

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

skessler’s picture

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

jhodgdon’s picture

denverdataman: Do you have CVS installed?

jhodgdon’s picture

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.

jhodgdon’s picture

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

jhodgdon’s picture

StatusFileSize
new45.34 KB
Unable to apply patch 537828-jhodgdon.patch
[ View ]

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 :) ).

catch’s picture

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.

jhodgdon’s picture

StatusFileSize
new106.99 KB

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

jhodgdon’s picture

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

Shai’s picture

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

arianek’s picture

I don't think I can speak to that path issue, or really to whether or not this should be broken up into separate issues - but it sounds from comment #13 from @webchick like creating one big patch for this isn't unheard of? Totally willing to roll separate patches, but just wondering if it's necessary.

But I do think that with the incredibly short timespan we have to get this done, the fact that 2/3 of the work is already spoken for, and that yes, the docs g.d.o group is still read-only that we ought to just get this done and not add extra steps, and barriers to moving forward at this point.

I like to just get things done most efficiently, and I think in this case it might be overkill to have a bunch of wiki pages.

arianek’s picture

StatusFileSize
new92.06 KB
new109.85 KB
new4.8 KB
Unable to apply patch help_block_1.patch
[ View ]

Did block module after saying goodnight to my folks (it was my birthday ;-) yes apparently, I am a huge nerd nowadays...or just letting it show!), I will sleep better knowing I have one down!

- For the love of dog, someone review this, it was my first time modifying link arrays and other things, and I am still very noob at PHP!
- Is "My Account" still the page name for /user/%/edit?
- I removed the mention of PHP visibility settings, as it seems to have been removed (http://drupal.org/node/224333#php_permissions - search for "visibility")

webchick’s picture

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.

Shai’s picture

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

Bojhan’s picture

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

batigolix’s picture

I'm working on the module "Statistics"

batigolix’s picture

StatusFileSize
new88.69 KB
new95.66 KB
new8.47 KB
Unable to apply patch help_statistics_1.patch
[ View ]

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

please update #49

batigolix’s picture

delete this comment please

jhodgdon’s picture

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

jhodgdon’s picture

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.

jhodgdon’s picture

THANKS everyone who is helping with this!!!!

My next batch of modules to claim:
simpletest
system
syslog

samirnassar’s picture

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

arianek’s picture

Issue tags:+d7help

@webchick says separate issues, so separate issues we do! ;-)

Block help has been moved to: http://drupal.org/node/632898

PLEASE TAG NEW ISSUES WITH "d7help" thanks!

@batigolix please post your patch as a new issue and tag with d7help, and post the link here, thanks!

arianek’s picture

ps. I tagged the other spinoff issues with d7help already.

pps. My parents are in town till tuesday, but I'll try and keep sneaking some time in on this - I have a feeling we might plow through this pretty quickly, so if anyone is dying for another one to work on and wants to steal any of my remaining ones (blog, book, comment), just let be sure to comment here and let me know! Otherwise, I'll get to them (and reviewing others' patches) more after midweek.

arianek’s picture

almost done blog - just have one more bit and will post the patch later on tonight

JuliaKM’s picture

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

arianek’s picture

Here be blog! (Def needs a review) http://drupal.org/node/633064

Shai’s picture

I'll do

  1. color
  2. profile

shai

arianek’s picture

Ahoy! Book! http://drupal.org/node/633134

(Apparently documentation writing is a good counter-balance for parental visiting time!) ;-)

JuliaKM’s picture

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

jhodgdon’s picture

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

JuliaKM’s picture

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.

jhodgdon’s picture

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. :)

arianek’s picture

you guys are all amazing, did i mention that? after i get comment done (hopefully in the next couple days) i'll see if any of the new ones that need the function added are still up for grabs.

then i think once we've knocked all these off, we should have a little patch review frenzy and cross check a bunch of each others' work for consistency's sake. (if @webchick doesn't beat us to it...)

*highfives* great work!

samirnassar’s picture

Shai’s picture

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

arianek’s picture

o hai comment module http://drupal.org/node/633750

batigolix’s picture

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

batigolix’s picture

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

batigolix’s picture

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!

jhodgdon’s picture

#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!

:)

jhodgdon’s picture

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

Shai’s picture

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

jhodgdon’s picture

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.

Shai’s picture

Jennifer,

Got it. Thanks for explaining. That makes sense.

Shai

winston’s picture

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.

arianek’s picture

alright menu help, let's do this, only one of us is coming out looking the same.

arianek’s picture

MMMMMMMMENU: http://drupal.org/node/634820 (all this late night doc work is starting to give me the sillies)

Shai’s picture

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

Shai’s picture

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

Shai’s picture

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

jhodgdon’s picture

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.

batigolix’s picture

im fishing "Tracker" out of the pool

jhodgdon’s picture

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

jhodgdon’s picture

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

batigolix’s picture

batigolix’s picture

Title:Help text for core modules needs standard, updates» Help text for core modules - update to conform to new standard
Issue tags:+d7help

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

JuliaKM’s picture

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

arianek’s picture

uh oh! and anomaly in the standard! see http://drupal.org/node/633750#comment-2281938

@juliakm suggested moving the "for more info, see handbook" bit, except for all the ones i've made it the last sentence of the About, since it was often closer to the top in most of the old help text. if it's being added at the end generally, that should be put in the template/standard so everyone does it!

also, i went back and checked and the node help (which incidentally was used to make the standard), which was already committed is missing that part altogether! so when a decision is made, that will need to be updated.

what say ye doc teamsters?

jhodgdon’s picture

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?

Shai’s picture

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

Shai

webchick’s picture

Issue tags:+D7 UX freeze

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

arianek’s picture

fair enough! carry on. :-) ps. totally thrilled with the progress on this!

batigolix’s picture

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"

jhodgdon’s picture

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

jhodgdon’s picture

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

jhodgdon’s picture

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

jhodgdon’s picture

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! :)

jhodgdon’s picture

Title:Help text for core modules needs standard, updates» Help text for core modules - update to conform to new standard
Issue tags:+D7 UX freeze, +d7help

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

batigolix’s picture

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

#639738: Help File Fixup: Path module

batigolix’s picture

opened the hunt for the upload module

arianek’s picture

Here's the new master list (I'm keeping track now that Jennifer is mostly away this week), now that the deadline for first patches has passed, everything that has no patch posted is up for grabs. Also, we got a bunch of reviews last night during the UX sprint, thanks to twitter, so please do post updated patches for any and all of them if you have time!

------

If someone has claimed a module, their user name will be listed here (UPDATE: all patches have first round posted, see below!). 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. Please post a comment when you've posted a new issue so we can add it here.

Currently updated to comment 161

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 - #640174: Help File Fixup: Contact module
dashboard - #637710: Help file fixup: poll and dashboard
dblog - #635282: Help File Fixup: dblog, php, rdf
field and field/modules/* sub-modules - #645776: Help File Fixup: field
field_ui - #645778: Help File Fixup: Field UI
file - #645802: Help File Fixup: File module
filter - #645784: Help File Fixup: Filter
forum - #632996: Help File Fixup: forum
help - #633836: Help File Fixup: Help module
image - #633808: Help File Fixup: Image module
locale - #645790: Help File Fixup: Locale and Translation
menu - #634820: Help File Fixup: Menu module
node - #632820: Documentation standard update : node.module
openid - #640198: Help File Fixup: OpenID module
overlay - OMIT - this appears to be an empty shell and not really a module
path - #639738: Help File Fixup: Path module
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 - #640348: Help File Fixup: Taxonomy module
toolbar - #636822: Help File Fixup: shortcut and toolbar
tracker - #635900: Help File Fixup: Tracker module
translation - #645790: Help File Fixup: Locale and Translation
trigger - #645796: Help File Fixup: Trigger
update - #640216: Help File Fixup: Update status module
upload - #639950: Help File Fixup: Upload Module
user - #633616: Help file fixup : user.module

batigolix’s picture

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

#639950: Help File Fixup: Upload Module

arianek’s picture

i'm taking over profile, should have a patch up shortly

arianek’s picture

jhodgdon’s picture

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

arianek’s picture

just did openid #640198: Help File Fixup: OpenID module

hey jennifer! been plowing through them as much as possible... there's LOTS to review and a couple more to write, so i'll cross my fingers they sleep in! :-)

arianek’s picture

annnnnd: update - #640216: Help File Fixup: Update status module

taxo is the only one sans patch, but my brain is done for today.

batigolix’s picture

arrrr. taxonomy

ok . ill give it a shot

batigolix’s picture

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

jhodgdon’s picture

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.

arianek’s picture

yay, we've got patches for all of them, and a few already committed to core! time for patch review-a-palooza! you guys and gals rock my world. :-)

jhodgdon’s picture

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

jhodgdon’s picture

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.

jhodgdon’s picture

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.

webchick’s picture

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.

Bojhan’s picture

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

lisarex’s picture

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

arianek’s picture

i believe they should be capitalized as well - and to be clear, prior to any of these patches, the modules names in the link to handbook in each help text WAS capitalized. that is why i actually started capitalizing the first one as well, to be consistent. then when this was brought up, i realized they probably should anyway, since it really is a proper name.

i'm not sure who is on UX team to contact about this, but i would like to keep this consistency and go back and change node - i think i will have to re-review that one anyway, since it went in before the rest and probably needs a couple tweaks for consistency.

jhodgdon’s picture

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. :)

arianek’s picture

w00t onward!

jhodgdon’s picture

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.

jhodgdon’s picture

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!

arianek’s picture

jhodgdon - lisarex and i have re-updated them all tonight, we're caught back up now. i am just making a mental note to go back for node module afterwards, the rest i have been screening for consistency before they go in. but yes, once they're all in we should certainly give it the once over!

jhodgdon’s picture

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

batigolix’s picture

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

arianek’s picture

thanks jennifer ;-)

@batigolix fix all what? you mean finish reviewing the patches?

i think we're doing great time wise. i haven't had any time today to put in and am out for the evening, but will be back at it again tomorrow evening and on the weekend for the final haul. not sure if it is help or hinderance to get totally new people doing final reviews at this point... (?) if someone feels strongly about an email go for it though!

skessler’s picture

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>';
     
arianek’s picture

denverdataman - this is for the update module i take it? there is already an issue started for this one here #640216: Help File Fixup: Update status module with a patch and feedback from @webchick - were you working off that? if so, please post your work there. and if not, then if you can work off of the patch and feedback there, that would be great. thanks!

arianek’s picture

i'm going to be at the woodworking studio this afternoon, so will check back in tonight!

webchick’s picture

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.

batigolix’s picture

Status:Needs review» Needs work
Xano’s picture

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.

jhodgdon’s picture

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

arianek’s picture

i think it's important to be clear that it's a module, since we are explaining how it works. besides, we can't change the standard this late in the game. if it's a real problem, you'll have to file an issue and roll a massive all-drupal spanning patch.

Xano’s picture

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.

webchick’s picture

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.

arianek’s picture

Status:Needs work» Needs review

changing this to "needs review" since there are just a couple patches in for reviews, and the rest are all waiting to be committed (and frankly the red is harshing my sea of green!). bangup job people. i never really thought we'd get close to making the deadline, to all who reviewed and rerolled, you kick major ass. <3

The last submitted patch failed testing.

arianek’s picture

silly bot. :-p fine!

webchick’s picture

Status:Needs work» Needs review
StatusFileSize
new0 bytes
Passed on all environments.
[ View ]

Here, let's do this. ;)

arianek’s picture

yayyyyyyyyyyyyyy :-) i know it's silly, but it makes me happy-like.

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community
arianek’s picture

WOOOOOOT!!! *crosses fingers for no rejects* ;-) good work people. way to make the awesome.

arianek’s picture

just thought to update the standard page to contain the link to the handbook as last sentence of about. (found a bug in node help which i'm gonna roll a patch for right away...) [#632280]

arianek’s picture

in case anyone is interested, i wrote a blog post about this experience http://affinitybridge.com/blog/story-drupal-7-core-help-update :-)

webchick’s picture

Status:Reviewed & tested by the community» Needs work

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

arianek’s picture

oh my! i'm gonna be pretty wrapped up in family stuff tomorrow, but then will have a couple nights to hack away... i dare someone to beat me to them!!! please? ;-)

jhodgdon’s picture

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

jhodgdon’s picture

Status:Needs work» Reviewed & tested by the community

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

webchick’s picture

Status:Reviewed & tested by the community» Fixed

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!

arianek’s picture

hey, if anyone has a sec (no obligation of course) i would muchly love some +1 on my admin perms request for d.o if you feel comfortable vouching for me ;-) http://drupal.org/node/660952

Status:Fixed» Closed (fixed)
Issue tags:-documentation, -Help text, -d7docs, -D7 UX freeze, -d7help

Automatically closed -- issue fixed for 2 weeks with no activity.