Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.On http://drupal.org/documentation there is a right sidebar block called "Help us Write Documentation".
We decided at the Vancouver docs meeting that we need to improve this block. I'm filing this issue currently in the Documentation queue so we can decide what we want to go into the block. When that is decided, we probably need to move this issue into the Webmasters or Infrastructure queue to do the actual edit (or maybe Ariane can do it?).
One idea that was suggested was to add a bullet list of links to issue queue subsets (e.g. tag or component searches) to this block, or to make it more like the Doc Contributors block we used to have on the pre-redesign drupal.org site (which had all kinds of useful links).
| Comment | File | Size | Author |
|---|---|---|---|
| #23 | 995334-fixmarkup.patch | 1.75 KB | jhodgdon |
| #18 | 995334-v2.patch | 1.88 KB | jhodgdon |
| #15 | 995334.patch | 1.87 KB | jhodgdon |
Comments
Comment #1
jhodgdonBump.
Someone pointed out on an unrelated issue that this block is still referring to the "Handbook". We really need to update this.
I think I can make the patch once we decide what we want it to say. Current text is:
Help Us Write Documentation
All content is written and edited by volunteers, please contribute where you see a need. If you have a Drupal.org account, you can edit a handbook page by clicking the “Edit” at the top of the page. You can also add new pages by using the “add a child page” link at the bottom. For more information on helping with the documentation, see quick ways to improve documentation.
We also need to update the copyright block to not say Handbook:
The Drupal handbook pages are © 2000-2011 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License
Propose text; once we decide I will make a patch...
Comment #2
jhodgdonCopyright block should probably say:
The Drupal.org on-line documentation pages are ...
I think that's the only change to that block. That block appears on every doc page.
Comment #3
jhodgdonFirst draft suggestion for the help with doc block (which only appears on the doc landing page):
Help Us Write Documentation
The Drupal.org on-line documentation is written by volunteers in the (link)Documentation Team(/link). Please (link)join us(/link)! After logging in, you can edit most pages by clicking "Edit" at the top of the page, and you can add new pages by using the "add a child page" link at the bottom. You can also use the (link)Documentation issue queue(/link) to propose changes and report problems.
Comment #4
Tor Arne Thune CreditAttribution: Tor Arne Thune commentedThe new texts in #2 and #3 sound good to me. Something that lingered a bit though, being a "newbie" in contributing to documentation: The text "Please join us!" made me think that I had to join some kind of documentation team to be able to edit pages in the documentation. As this is not the case, maybe it should be clarified, as in the old text, that all that is required is a Drupal.org account.
Suggestion:
"Please (link)join us(/link)! After logging in to your normal Drupal.org account, you can edit most pages by clicking "Edit" at the top of the page, ..."
I'm not sure about the word normal though. It's a try at clarifying that no extra permissions are required to edit the documentation.
Comment #5
jhodgdonI think we actually do want people who wish to help with documentation to read the section on how to join the doc team, since it has guidelines, suggestions for what to do, etc.
Comment #6
Tor Arne Thune CreditAttribution: Tor Arne Thune commentedGood point. In that case, the text will do the trick.
Comment #7
arianek CreditAttribution: arianek commentedI have a few suggestions:
"Help Us Write Documentation" --> "Help Us Maintain Documentation" (implies we don't just want to add more but make it better)
"on-line" --> "online" (as per the style guide)
"volunteers in the Documentation Team" --> "...the Drupal community in co-operation with the Documentation Team." (I do get the feel that thinking people have to join a team is taken as a barrier by some)
"Please join us!" --> remove (trying to also make it sound like you don't *have* to "join" to help)
" After logging in..." --> "When you are logged in..." (just makes more sense to me)
"...link at the bottom." --> "...link at the bottom of any documentation page." (to make it clear what bottom we're referring to)
"...to propose changes..." --> "...to propose major changes..." (so that people realize if it's a small change they should just go for it)
This would give us:
Help Us Maintain Documentation
The Drupal.org online documentation is written by the Drupal community in co-operation with the [Documentation Team]. When you are logged in, you can edit most pages by clicking "Edit" at the top of the page, and you can add new pages by using the "add a child page" link at the bottom of any documentation page. You can also use the [Documentation issue queue] to propose major changes and report problems.
Comment #8
jhodgdonThat text is fine with me. Any other comments/approval needed, or should I just make a patch?
Comment #9
arianek CreditAttribution: arianek commentedi'm going to tweet this - i don't think anyone else has noticed it ;)
Comment #10
batigolixlooks fine to me
Comment #11
lisarex CreditAttribution: lisarex commentedCool, arianek's edits address most of what I wanted to revise, content-wise. But right now it's a blob of text that is difficult to scan. How about:
Help Us Maintain Documentation
The Drupal.org online documentation is written by the Drupal community in co-operation with the [Documentation Team]. When you are logged in, you can:
Comment #12
arianek CreditAttribution: arianek commentedList format is fine by me!
Marking needs work, as I think Jennifer can probably go ahead and roll the patch at her leisure/approval. ;)
Comment #13
jhodgdonOk I will roll a patch. Setting status back to "active" as usually we use "needs work" for when the patch is no good. :)
Comment #14
Tor Arne Thune CreditAttribution: Tor Arne Thune commentedLooks good to me :)
Comment #15
jhodgdonHere's a patch. After attaching it here, I'll apply it to my dev site so we can look at it, so stand by... I made a couple of minor edits (like adding . at the end of the bullet points).
Also changing the project to the drupalorg module, since that's where the patch goes.
Comment #16
jhodgdonWell, the patch is applied here:
http://jhodgdon.redesign.devdrupal.org/documentation
The reset.css file that is in the bluecheese theme has taken away all styling on bullet points. Lame. How would we get those bullet points to display? The HTML is correct -- it's just that the CSS has no space between the LI elements and no bullet points.
Comment #17
jhodgdonI looked through the bluecheese styles.css and it doesn't look like there's a handy class I can add to the UL to make the list style re-appear, so this would require a patch to the bluecheese module in order to have bullets visible in the block.
So we either need to rethink #11 or also make a bluecheese patch. Are bullets forbidden by the style guidelines on drupal.org or something?
I also realized my patch needs a bit of work, because I thought the suggestion in #11 was slightly awkward where it says "of pages", but I only changed on of them to "of the page".
Anyway, after we figure out what should be done about the bullets, I'll make another patch.
Comment #18
jhodgdonHere's a new patch with the wording consistent. Still need to figure out bluecheese/bullets.
Comment #19
drummCommitted to Drupalorg.
For the bullets, this is by design. https://infrastructure.drupal.org/drupal.org-style-guide/typography.html and the prototype didn't have them. We have adjusted whitespace between list items to handle multi-line items and added bullets to lists in the main content area.
Comment #20
jhodgdonSo you used bullets or something that looks like paragraph breaks in this block? I wasn't sure it was ready to deploy with the formatting I had there...
Comment #21
drummYes. http://drupal.org/getting-involved shows how these lists look, although with some extra text. The right sidebar of project pages isa good example of how these lists look with links only.
Comment #22
jhodgdonGetting Involved is using P tags and not UL/LI. Do we need to adjust this block to use P tags as well? The getting involved page on my dev site looks fine, but not the doc home.
Comment #23
jhodgdonLike perhaps this patch?
Comment #24
jhodgdonUgh. Strange quotes in there... was that intentional? seems to be in the checked-in version at the moment...
Comment #25
drummSorry, forgot to mention I put curly quotes in.
And I noticed the list styling in sidebar expects
<div class="item-list">, which will put some whitespace between items.<p>has more whitespace. I'll go ahead and commit a version with<p>.Comment #26
drummCommitted. I think this is fixed now.
Comment #27
jhodgdonthanks! I guess we can adjust again if it looks bad after it's deployed.
Comment #28
arianek CreditAttribution: arianek commentedI just realized the block below that one with the copyright says "The Drupal handbook pages..." can we update that while we're at it to "The Drupal documentation pages..." or "Drupal's online documentation..." ? Or should I file a separate issue?
Comment #29
jhodgdonI thought there was an issue about that block, but I'm not seeing it. Yes, the text should be changed; probably on a separate issue?
The current text is:
The Drupal handbook pages are © 2000-!year by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License.
Comment #30
jhodgdonNew issue:
#1056490: Doc copyright block refers to "handbook" and shouldn't
Comment #31
drummDeployed