Change docs page layout for "community documentation"

This also depends on #733908: Add noderef field for project to doc pages being done, since that information also needs to be moved to the sidebar.

Note: I just edited the issue summary to the new proposed page layout.

Adding new tag. These issues tend to get moved to other issue queues, so we need a unifying tag in order to find them consistently.

Update to new mockup

I just updated the issue summary, since we have a newly approved plan. This issue is still postponed until 3 dependent issues are resolved.

Update to new plans

Updated issue summary again (flag vs. filing an issue to report the page)

Change from issue report to flag for reporting pages

Updated the issue summary with the current plan. This issue can now be taken on by someone -- no blockers!

Slight plan update: After thinking about flags for reporting pages to the moderators, we think there will not be information about what is wrong and the moderators will have to hunt around and/or guess. So we want to change back to using a link saying "report to moderators" as in the mockups above, but instead of it being a flag, it will file an auto-filled issue. This can be done as part of this issue; updating issue summary accordingly.

Update to current plan

I'm going to take this one on, since no one else has stepped up yet.

I've requested a dev server to work on it: #1327600: Dev machine images: remove one, add one

I'll post requests for comment/review when I get it going.

OK, I have a first pass of this ready to review (see notes at bottom of this comment).

For review, here are three pages on drupal.org:
-http://drupal.org/node/1326928 - doc node with no revisions
- http://drupal.org/requirements - doc node with lots of revisions, requires doc maintainer permissions to edit
- http://drupal.org/patch - community node with revisions

Here are the pages on the test site:
- User name drupal, password drupal to get past the htaccess login
- To log in, I've set up user nothingspecial, password nothingspecial as a generic user, and user special, password special for a user with doc maintainer permissions. You should also try viewing them not logged in.

http://community-docs-drupal.redesign.devdrupal.org/node/1326928
http://community-docs-drupal.redesign.devdrupal.org/requirements
http://community-docs-drupal.redesign.devdrupal.org/patch [added taxonomy, changed status]
(You can also click around and see what other pages look like.)

NOTES:
- What this issue is supposed to be doing (screen shot):
1. Remove one level of navigation, and change Documentation tab to say Community Documentation.
2. Header lines at top of page giving authors and dates.
3. Meta-data information moved to right sidebar.
4. Line at bottom saying where to get support.
5. Links for Report to moderator (creates an issue with stuff filled in).
- NOT doing on this issue: discussion stuff, and sidebar section Related Projects.
- We didn't specify what to do when the user is not logged in or couldn't edit the page, so I improvised (omit edit link; if not logged in, omit report to moderators link and put "log in to edit" where edit links would be).
- We didn't specify what should be different on a documentation vs. community page, so I improvised (omit report to moderators and detailed contributor information).
- We didn't specify what should be shown for a node with no updates since initial creation (or only the original author updating), so I improvised (omit list of updates, and word "too" on "you can edit" link). I also decided the people listed as contributors should all be different, so eliminated duplicates.

Reviews welcome! I'm sure I overlooked something...

Here are the patches for this change -- one for the bluecheese theme, and one for the drupalorg module (created with bzr diff).

After patching, you also need to put the block whose admin name is 'Documentation status/about sidebar' in the right column. And clear the cache, of course.

I chatted with jn2 in IRC just now. She pointed out:
- Color of headers in About section was not black, so contrast wasn't good between headers/information.
- Keywords were supposed to be separated from the other information.

Both of these are now updated on the site. New patches attached.

jn2/arianek pointed out the labels in the About section were a different font and the line height was wrong there. Fixed that, new bluecheese patch (drupalorg patch from #11 still operational).

Also moving this to the drupalorg project.

Tagging in case the usability/accessibility people would like to chime in. Test site information is in comment #9 above (http://drupal.org/node/1289072#comment-5188942).

I also just tested in IE7 on my Windows VM and it looks about the same there. Phew! :)

I made a slight change to the logic for building the list of contributors. Pages look the same. New patch for drupalorg module is attached; patch in #13 for bluecheese is still valid.

You know, after 190 comments on the main issue, I think we all came to agreement on the design (including usability concerns). And three of us (jn2, arianek, and I) looked at this implementation carefully yesterday and agreed it matched the design mockup. So I think this is probably good to go.

To deploy:
a) Apply the drupalorg project patch in #17 (patch from bzr, so use the appropriate -p3 probably to apply it)
b) Apply the bluecheese patch in #13 (ditto).
c) Clear the cache so the new block/theme stuff is recognized.
d) Put the block whose admin name is 'Documentation status/about sidebar' in the right column, above the book navigation block. The code will only display it on book pages.

I guess it's not up to me to deploy this, so unassigning. This is ready to go...

wrong version

RE #22 - Thanks -- nice to have someone finally review the patch!

- Agreed on the broken HTML.
- I will check_plain the term names... I wasn't too worried about escaping them, but you're right, they should be.

Here's a new patch that fixes the problems identified in #22.

I'm assuming this was just meaning that the term names should be run through check_plain(). $class here is one of several literal strings, so it does not need further escaping. I also ran the vocabulary name through check_plain().

Attached is a patch for the drupalorg module. Patch in #13 for bluecheese is still valid. Deployment instructions are in #18 (except use this patch not #17 for drupalorg).

Sorry, that @todo should be removed.

I would prefer that you leave the workspace until this is finalized... I will need some space to try things out, refine patches, etc.

I won't be around much today to discuss this... probably tomorrow (Wed.) through the rest of the week... sorry!

The docs team does not have governance over things outside of docs, so we don't want to add moderation responsibility to the docs moderation team. Therefore we don't want to treat the non-docs pages the same as the docs pages. Please don't make that change.

As far as styling goes... Do we really have to go back to the drawing board on this? We had this design reviewed by about 15 people (including the Drupal usability team) over the course of many many many design iterations on #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. and they all thought it was just fine. So now we have to redo it? Is there any possibility you could rethink that decision?

So can you be specific about what you want changed now in order to get this finalized (and perhaps post the patch you want to commit vs. the last one I submitted)?

Oh. And if you do decide you want the design to be revisited, can you please go back to #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. (where that decision was made) and set it back to "needs work" so we can rework it there. I'm not going to agree to any design changes without going back to the group who OK'd the existing design (I'm not a designer).

The color for the No Known Problems status is OK, but I'm not sure about the others. Needs technical review:
http://docs-review-drupal.redesign.devdrupal.org/node/1326928 (drumm's version)
vs.
http://community-docs-drupal.redesign.devdrupal.org/node/1326928 (my version)
I think the yellow color I had proposed makes more sense for Needs Technical Review than a light green (green = all is well to me).

Same with the "needs updating" status:
http://docs-review-drupal.redesign.devdrupal.org/requirements
And "incomplete":
http://docs-review-drupal.redesign.devdrupal.org/node/648458
And "Needs copy/style review":
http://docs-review-drupal.redesign.devdrupal.org/node/1353118

On the other hand, insecure code and Deprecated look good:
http://docs-review-drupal.redesign.devdrupal.org/node/93984
http://docs-review-drupal.redesign.devdrupal.org/node/83121

I also agree with Ariane's comment in #33.

I also noticed that on your site, the nav header says "Community Documentation Home", not just "Community Documentation". This seems odd -- the rest of drupal.org doesn't do that, and it's very long (and doesn't match our design). And you restored the multiple-levels of navigation, which we had intentionally removed in the design. See screen shot. [These are both in item #1 of the issue summary here.]

Also... reviewing the patch, there seems to be a bunch of other unrelated stuff in it, like redefining what's part of Getting Involved. That makes it kind of hard for me to review... But it looks like some things that we intentionally put just on the Documentation section page were also added to the Community section pages in your patch. I'm not sure that is a good idea?

I don't understand what you're saying in comment #36... This issue is not about a bug fix. This issue is asking for a fairly straightforward (I think) design change to the documentation pages (and only the documentation pages) on drupal.org, which was approved through 193 comments (so far) of discussion and many people contributing and approving in the end. The approved design includes the yellow (not green) color, and the removal of the extraneous "Documentation" section header. If you are not willing to commit/deploy the approved design, please don't discuss that here -- we will need to go back to #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. and set it back to Needs Work and explain why what was approved can't be done or should be reconsidered.

If you want to refactor the crossite module, that's fine too (it would be great if that whole module made more sense), but let's not mix those changes up in this issue. If you're fixing another bug in the crossite module, let's do that on another issue too. And if you want to postpone this issue until some other changes go in, then you can -- just set this to Postponed and explain why. That is up to you.

Meanwhile, on this issue, can we please just stick to the approved design, and get all the changes in at the same time, and only those changes? Thanks.

Also drumm: you seem to have removed the login information from the "comment" file in your docs-review-drupal.redesign.devdrupal.org area. Can you set up a user so we can test and see what it looks like logged in? Thanks.

AGAIN if you want to change colors or anything else from the design PLEASE can you do it on the other issue?

Sorry for shouting there.... It's just a very frustrating situation to have submitted this change more than two months ago and still have it not go in. This is a critical change for the Documentation team, and I hope we can get it deployed sometime soon...

So, just to clarify what I mean in #41... We went through many design iterations with many people (including the usability team), and came up with a design, which included choosing colors for the different statuses. Now it seems like you've arbitrarily decided to change them. I didn't come up with the design -- I am neither a usability nor design expert. I just implemented the design.

So if you would like to change the colors from the agreed-upon design, we need to open up the discussion on the design issue, not here. I personally don't like the change you've made -- to me, the light green you chose for the "these pages probably have problems" is too close to the green of "these pages are fine", and the yellow color that is in the agreed-upon design seems better to me. But again, I'm not a designer/usability person. So if you'd like to make a case that your design is better, please feel free to open up #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. again and discuss it there. But it is not OK to just change the design on this issue without opening up the design issue again. Right?

Regarding postponing part of the changes -- do as you think is best. I would obviously prefer to get the whole change in now, but I am not managing/maintaining drupal.org, so I will leave it to you to schedule the changes as you see fit.

I have to run out to the dentist now, but I'll try drush uli to test your current implementation as a logged-in user and see if I see any other deviations from the design.

OK. I think the only differences between our intended design and what is now on
http://docs-review-drupal.redesign.devdrupal.org
are:
a) Color for the needs-review types of page status. It should be yellow, not light green. I suggest color #FFFFDD, which is what is used for Needs Review for issues.
b) Extra "Documentation" header line at the top (I understand this change may be delayed for whatever reason, but we'd like to get it in and it's a really easy change in the crosssite module, so if you can possibly just do it now, we'd appreciate it).
c) Tab label says "Community Documentation Home" instead of just "Community Documentation".
d) We would like the "You can edit this too" link to have only "edit this" as the link, not the whole sentence.

I can make those 4 changes in your docs-review-drupal environment if that is OK with you. If you prefer to do them, here's where they are:

a) Bluecheese theme styles/styles.css:
#block-drupalorg_handbook-meta-sidebar .page-needs-work {
background-color: #E6FCB6;
}
Change this to #FFFFDD

b) First hunk from my patch in #24.

c) Second hunk of your patch in #32.

d) in drupalorg_handbook_before_body() from your patch:

+    if (node_access('update', $node)) {
+      $edit_link = l(t('You can edit this page'), 'node/' . $node->nid . '/edit') . (empty($contributor_list) ? '.' : t(', too.'));
+    }

Change this to:

    if (node_access('update', $node)) {
      $edit_link = t('You can <a href="!url">edit this page</a>'), array('!url' => url('node/' . $node->nid . '/edit')) . (empty($contributor_list) ? '.' : t(', too.'));
    }

Let me know how you'd like to proceed... Let's get this done!

The color you chose is fine with me -- it is yellow-ish (signalling "maybe a problem"), and distinct from the other colors.

The header section is OK too. We'd prefer to have one less layer of tabs, but I think that will come on the other issue and it's not as big of a deal as just getting it to say "Community Documentation" prominently at the top.

Anyway, I tested all the above page links, both logged in and not logged in, and I say "Let's go!!!". Ariane took a look too (via IRC) and said "yes" too. :)

Thanks for finding a solution that works for everyone, and thanks for being careful drumm. Although it was frustrating when we wanted to get this deployed, it's a good idea to work towards consistency. :)

Note: I haven't reviewed the code carefully yet, just the look of the new site... next comment...

I took a look through the code. The only very minor thing I found was:

+++ sites/all/modules/drupalorg/drupalorg_handbook/handbook-contributors.tpl.php	2011-12-29 22:30:27 +0000
@@ -0,0 +1,19 @@
+<?php
+/**
+ * @file
+ * Displays a list of contributors and call to edit a page.
+ *
+ * Available variables:
+ * - $created: Formatted created date.
+ * - $updated: Formatted last updated date.
+ * - $contributors: Several recent revision authors (formatted).
+ * - $edit_link: Link to edit the page.

I believe $created is the formatted created date and author here, not just the date, and $edit_link is a link to either log in or edit the page.

But this is a minor technicality that can probably be left alone. Let's do it!

THANK YOU drumm!!!!!!!!!

Check out arianek's comment on the Mother Issue:
http://drupal.org/node/1278256#comment-5462944

It worked! (at least for one person)