This patch adds structure to the existing help text for the comment.module. It includes additional links to the API documentation and theme template files. The patch does not include styling, however, it should look like the revised admin screen #228236: Redesign /admin (for example: http://www.flickr.com/photos/emmajane/3592224815/).
New (unstyled) content:
http://www.flickr.com/photos/emmajane/3602953320/
New headings include:
About
Use (with several relevant sub-sections added as a definition list)
Theme (links to API docs with template variables, should be automatically generated)
Develop (links to API docs, should be automatically generated)
Comment Administration pages (currently automatically generated)
| Comment | File | Size | Author |
|---|---|---|---|
| #15 | Comment-help-3.png | 67.29 KB | emmajane |
| #14 | comment-help_3.patch | 5.39 KB | ano1 |
| #10 | Comment-help-2.png | 66.57 KB | emmajane |
| #10 | comment-help.patch | 5.34 KB | emmajane |
| #8 | comment-help.patch | 5.22 KB | emmajane |
Comments
Comment #1
catchBy automatically generated do you mean for every module? I'm not sure how we'll manage that. Tagging anyway, didn't review the text changes yet.
Comment #2
emmajane commentedThe automatically generated text is scope creep for this patch, but: Currently the bottom-most section of the help screen ($module_name administration pages) is not editable as part of the regular help text. I'm not quite sure where this list is generated from yet, but in theory other sections could be generated as well, which would make it easier to have consistent help across all modules.
Comment #4
lilou commentedSetting to 'needs review' - testbot was broken.
Comment #6
Bojhan commentedThis looks oke, please do some of the last fixes proposed though. I would also say to remove node from the interface.
Comment #7
karschsp commentedUpdating patch to try and get past test bot.
Comment #8
emmajane commentedRerolled the patch to remove the link to "node" in the About description. Screen shot and patch attached.
Comment #9
ano1 commentedI have applied the patch successfully. After reading the text I have a few suggestion and questions.
Under about: The wording "creating ad hoc discussion boards" leaves me confused and I know what the comment module does. Sadly, I can't think of an alternative.
Under use->closed I would recommend rewording it to: allows existing comments to be viewed but no new comments to be added.
The statement below that should be: The settings are available in a tab named, "Comment settings.". as the fieldsets are now tabs in D7.
Under User Permissions there should be an and between: Post comments, Post comments without approval.
Other than the aforementioned nitpicking stuff, this looks good.
Comment #10
emmajane commented@ano1 Great review, thanks!
I've updated the text for the "About" to the following:
"The comment module allows visitors to add their remarks to site content."
I think that's better than the ad hoc discussion stuff? (That was leftover from the current version of the help text.)
For closed comments I've adjusted it to:
Closed: allows existing comments to be viewed but disables the submission of new comments.
And I fixed up the language about the tabs for D7.
let me know what you think of the new patch!
Comment #11
Bojhan commentedWow, this is looking very good - is this a structure that we could apply to more cases?
I would put a empty-line after submission of new content.
Comment #12
ano1 commented@Emmajane my pleasure thanks for guiding me through the process
I was successful in applying the patch. I like the rewording, and feel it's a lot clearer. I have one comment on the underlying HTML markup for the help text. Might it make sense to change the UL of terms such as those under Use (hidden, open etc) to a DL. Since these items are terms (DT) with definitions (DD). If you agree I am happy to post the patch I created to test this. Otherwise I would say this is ready to be marked as finished.
Comment #13
emmajane commented@bojhan yes, the structure is one that I hope to apply across all help pages. The formatting for a new line is because of the CSS rules that are applied. There is no spacing between the end of a list and the beginning of a paragraph. That will need to be dealt with in a separate issue as I don't want to force markup just to correct the presentation.
@ano1 Although I agree that a DL might be more appropriate for the nested list, it will require style/formatting changes to keep the terms and definitions inline. Without the formatting updates the headings will generate a new line and the definitions will fall below with an indent. I don't think this will significantly improve the legibility of the text because the definitions are so short. That's just what I think though. You can always go ahead and roll a patch with the changes and we can take a look at it! :)
Comment #14
ano1 commentedEmmajane the formatting issue was the 1st thing I noticed when I converted the UL to a DL. I am going to submit it so you can see. I have a feeling we will be sticking with yours. Let me know what you think
Comment #15
emmajane commented@ano1 It's not as bad as I thought it was going to be. I've attached a screenshot.
@Bojhan: What do you think?
Comment #16
Bojhan commentedPersonally I would avoid the indentation, indentation should only be used if really necessary - cases such as indentation for important lists is more appropriate then descriptions.
Comment #17
Bojhan commentedGreat, this started the work on all help text in core. I am closing this issue to continue work in #37828: Splitting into front and control panel