Note: This issue is closed -- for follow-up comments, please use one of the other issues referenced in this summary. Thanks!


The current Documentation on is not well maintained, because it has grown to the point that it is not really maintainable by a formal Documentation Team:
- Because anyone can edit and add pages, it grows into a pile of spaghetti, with a few nice meatballs of great content sprinkled throughout.
- Even though they have permission to do so, people are afraid to click "Edit" to fix pages, and the status of pages (a taxonomy) is not updated because people don't realize they can change it if they click "Edit". Instead, they tend to add comments, which introduces more maintenance problems.
- Having the expectation that this documentation is overseen by the Documentation Team leadership has led to several past docs team leaders burning out, and is unsustainable.

This issue is primarily for discussing the minimum initial changes needed to resolve this problem which has been done, so this issue is now closed. Thanks!

Discussions for additional improvement ideas should happen on this follow-up issue:
#1287784: Follow-ups to improve the community docs
Discussion regarding the redesign of the navigation portion of the page has been moved to this issue:
#1289090: [meta] Improve search/navigation for d.o community docs
Discussion of a new "curated" docs area that is more tightly controlled is being discussed on:
#1291058: Discussion: Make a curated docs section/system
And in the Remaining Tasks section below, there are a few follow-up issues for specific ideas.

Proposed resolution

The first step in resolving this problem is to turn the current Documentation into "community documentation". In other words, we need to remove the expectation that there is a Docs Team who maintains this documentation, and replace it with the expectation that the community as a whole maintains this documentation. The formal Docs Team will only be responsible for moderation and infrastructure.

What needs to be done in order for this to happen:


Have headers/sidebars that make it clear that it is maintained by the community, and that they can/should edit it and add to it, and that you need to "edit" to change status if a page needs work.


Provide discussion ability on each page (which, as a note, we already have with comments).


Full edit permissions with images and (hopefully, future?) videos for all on all pages.


Moderators for spam removal and dispute resolution.


Some way for people who want to improve the doc to find pages that people have identified as problematic.


Edit the Contribute to Documentation section and Docs landing page sidebar to reflect this new reality.

A screen shot for (a) and (b) is in comment #183 below.

Remaining tasks

The plan is to roll this out in several phases, as indicated below.

  1. [phase 1] (a) above (header/sidebar redesign). Issue (DONE!): #1289072: Change docs page layout for "community documentation"
  2. [phase 2] In the proposed mockup: We want each Book page to be able to reference one or more contrib projects. Issue (assigned, in progress): #733908: Add noderef field for project to doc pages
  3. [phase 1] New taxonomies for Book pages: Level (beginner, intermediate, advanced). And Keywords (tagging). (presumably this is in the admin UI). Issue (DONE!): #1300622: Add two taxonomies to book pages
  4. [phase 3] (b) above - We might want to use the Talk module to move the comments to a different tab, or use forums for discussion? Issue (in discussion) #1402848: Put documentation comments in a separate tab Note: we had considered using forums for this (#1027608: Use forum to make Discussion tab/block for Book pages), but the thought currently is that this is too big of a change, and we'll probably keep using regular comments for now. If we used forums, we would need to convert the existing page comments into forum posts, so they can become the new discussion tabs (in a database query in a drupalorg.install update function?). And we would also want to turn off book page comments with another database query. And we would also want to revive existing dead/deprecated Documentation forum (presumably this is in the admin UI) TBD
  5. [phase 1 or ASAP] (c) above: Now that #528682: Allow inline images to be posted to project pages, docs pages, and comments without any special permissions has been deployed, we need to also figure out which pages are OK to change the input format back to Filtered HTML (probably most that are currently Documentation), and do that in a big database query. This is issue (NEED INPUT ON THIS): #1275424: Deal with documentation role and documentation input format
  6. [phase 2] (d) above: We need to recruit moderators - TBD - and it's also part of the "edit contribute pages" (item f). We also need to add a flag to the page to report it to moderators. Note: Each time someone reports a page, it will create an issue, and this is now part of the redesign item #1.
  7. [phase 2] (e) above: We already have . It will need to be tweaked a bit since we won't have comments (maybe), and we will have a flag for moderation, but if people are updating status and starting discussions, this should be enough. It does need to have the new taxonomy added to it. Issue: #1299822: Update Docs Management view
  8. [phase 3 or ongoing] (f) above: Editing Contrib to Doc - (DONE!) (see also item d).
  9. [phase 2] Need to edit the sidebar block about help maintain on the page -- should wait until things are closer to deployment probably. Issue (in progress): #1401960: Edit the Documentation landing page sidebar block
  10. [phase 3] Once this whole thing is deployed, convert existing issues in doc project into forum posts with appropriate book refs or comments (or whatever we are using for discussions) (this is a manual process, to be done in a sprint). Issue (in progress): #1421874: [meta] Documentation Issue Queue Cleanup :
    • Issues asking for new docs to be written can be closed as "won't fix" with a comment saying we aren't using the issue queue for this any more. Same for structure/placement/navigation issues.
    • Issues pointing out problems in pages will have to be gone through manually. For each one that is open, the page status should be changed to something appropriate, and a comment added to the page pointing to the issue and saying 'this has been identified as needing to be fixed', and then closed as "won't fix" with a comment saying we aren't using the issue queue for this any more. I think we can make a process for this that sprinters can deal with.
    • Issues in the API docs and Spam/Vandalism queues can be left as-is.
    • Issues in the "apply to be a docs admin" category should be gone since that was mostly for image permissions.

User interface changes

The headers, nav tabs, and sidebar of current documentation pages will change as described above.

API changes


Members fund testing for the Drupal project. Drupal Association Learn more


jhodgdon’s picture

Note: the idea of having comments as a "discussion" tab was part of the d.o redesign concept:

MGParisi’s picture

+1 to this.

Wiki's have allot of flaws, and we will see some people mention them, but the current doc book system navigation has been impossible to maintain for a long time. The one thing that really excites me is that a wiki really gets people the idea that they CAN make changes rather then goto someone else to make them.

Other solutions are solved within the Prairie initiative's. I suggest all familiarize themselves with both.


arianek’s picture

subscribe +1

webchick’s picture

Assigned: Unassigned » Dries

Jennifer Hodgdon asked for feedback from both Dries and I on this concept to help move it forward. Subscribing for now, and adding to Dries's hit-list.

There's also the overall documentation team plan at which she would like our feedback on as well.

wfx’s picture

If we are getting away from the hierarchical book format with this freeform Wiki documentation can we add in-page Table of Contents? Table of Contents Module This is a huge usability perk for most Wikis.

jn2’s picture

Regarding #1, comments as a discussion tab. I'm sure this is common knowledge, but just to get it into the conversation here:

Most every wiki allows for comments by topic on the discussion page, each topic with a separate edit link. They function as a combination of issues and comments. They don't produce the infinite threads we see so often on d.o, with each issue/topic having its own separate thread. Much easier to follow. Comments can extend far down the page, making it hard to see the original text. A separate tab allows the contributor to read the issue, then easily switch back to the doc. Topics could even be collapsible so you only see the details of issue you're concerned with.

And #5's in-page TOC would be a great addition.

silverwing’s picture

I mentioned this in my comment on the groups post, but I'll add it here.

For the Docs to change, we need to rethink how we approach it. Simply calling it "Wiki" and treating it just like Documentation isn't going to improve things. (Just as the move from Handbook to Documentation didn't help a lot.) We need a bit of a paradigm shift.

I would love to see the Wiki be taxonomy based. When searching for something, having a list of terms to choose from would be far better than our current hunt-and-peck-and-search-and-fail approach.

My fear is that with our current book-style approach, nothing really changes except for the name.

lisarex’s picture

One other concern is that we're going to need to improve the search experience within Documentation, particularly filtering and identify the doc type in the search results. I don't have any solutions, other a) identify additional facets b) mockup theme/UI improvements etc. I would be happy to usability test the before, after and polish up phase.

re: #7, that paradigm shift might come when user profiles have badges or some sort of 'reward' for being active in Documentation. But there are other issues for that so don't want discussion to shift to that here :)

wfx’s picture

DITA has been mentioned many times in these discussions, will this technology be available soon to the Documentation team or is it still in the planning phases?

Sree’s picture

+1 subscribe

pgrond’s picture

subscribe +1

jhodgdon’s picture

New concrete suggestions I'm seeing since the last issue summary:

#5 - Table of Contents module - this would auto-generate TOC and also outline-number the headers on the page. Sounds like a reasonable suggestion to me, and has one +1 above. Any discussion before I add this to the summary?

#6 - Comments by topic... We already have threaded comments with subjects on Book pages. So I'm not sure how what you're suggesting differs from what we have. Can you clarify? Are you suggesting we dump the existing use of the Comment module and use some other type of module entirely to do this? Or is it some kind of formatting we would apply to existing comments (like the ability to collapse/expand by thread)? I'm just trying to understand what you mean. Maybe link to an example of this on an existing wiki so we can see how it differs from what Comment module can accomplish?

(note that the mention in #6 of comments in separate tab is already in the issue summary).

#7 - "I would love to see the Wiki be taxonomy based. When searching for something, having a list of terms to choose from would be far better than our current hunt-and-peck-and-search-and-fail approach." ... Can you clarify what you mean here with an expanded explanation or a mockup? I am not following your idea.

#8 - Additional search facets for the Doc Wiki. Such as? I guess this is related to #7 -- is that the same thing?

#8 - rewards/badges as motivational factors - being discussed elsewhere I guess (not sure where)

RE #9 - DITA in the Wiki - I personally don't think that is feasible (depending on what you mean by "using DITA"). The main important aspect of DITA, as far as I can tell, is that documentation is broken down into atomic chunks (called Topics). And it takes considerable discipline to break your content down into concise topics that are not a mixture of concepts, reference, and tasks. Expecting the vast community to do that in the Wiki is, I think, not realistic. Besides which we have a huge amount of existing content that is never going to be broken up into DITA-sized chunks. Other aspects of DITA, such as the ability to export content to DITA-formatted XML (and then do other things with it), are also not very realistic for the existing Wiki, since the existing content is not formatted right for it and lacks the DITA meta-data. We don't want to throw out our existing content... so I think this is a non-starter.

One aspect of DITA that we could consider for the Wiki is the ability to add multiple outlines/maps (rather than being tied to one Book outline). That could certainly be useful, and could be added at any time that someone comes up with a solution for it that would allow us to transform the current Book outlines into these maps. The solution would also need a way to navigate (like we have currently: if you land on a particular page, you would want to be able to see the nav in whatever outlines exist for that page).

wfx - maybe you can clarify what aspects of DITA you think would be useful for the Wiki?

And everyone, maybe you can comment on whether you think multiple outlines ability should be added as a desirable feature to the issue summary?

wfx’s picture

@jhodgdon I was asking about DITA because it seems to be the magic tool everyone is hoping for that will improve Documentation. The features I see referenced most when DITA is brought up it is the ability to reuse content and the ability to easily find content. The latter can probably be accomplished via taxonomy though I'm not a developer so I'm not sure how that would be done.

On a side note, my unsaid hope in asking that question about DITA was seeing if the project had moved since the DITA Distribution Discussion a year ago. I haven't followed that discussion in a while and didn't know what the status was.

jn2’s picture


#6: I think the difference between the wiki discussion page and comments, the thing that combines aspects of comments and issue queues it the one bold title for each issue, and at least on some wikis, a separate edit link for each issue. For an example, look at, the example wiki Silverwing cited on g.d.o., or any discussion tab on Wikipedia (here's a link to the Drupal talk page: Having a single title per issue makes it easier to see what issues exist. I also think this format will discourage people from looking for support here, but maybe that's wishful thinking.

Itangalo’s picture

Sorry for kind of leaving the subject of this issue – my comment concerns both the wiki and the "curated docs".

If we have the possibility to set maintainers for individual sections of the wiki, I think it makes sense to have the "curated docs" being selected – promoted – sections of the wiki. That would allow assigning teams (maintainers) for curated docs, and allow assigning different teams for different sections of the curated docs.

There could of course be discussions about why their section X is promoted while my section Y explains the same topic much better – but that's a discussion we'll face anyway. And it could definately make sense to replace a poorly maintained "curated" section with a well-written and up-to-date "wiki" section – something that would be easy to do if they are both managed as wiki sections.
(If we want "objective" metrics, we could try exposing statistics such as "512 edits the last 30 days" or "1024 open issues".)

(If would also be interesting to optionally allow wiki sections to be open – editable by others than the maintainers. But that's another issue.)

Man, I want to try to build this site right now, in D7!

jhodgdon’s picture

RE #13 / DITA - OK, so you're really asking for better navigation and searching. That is a good idea.

And content reuse, which I don't think we can really accomplish easily with all of the current wiki/doc content, so I don't want to add it even as a "wish list" for the wiki.

RE #14 - You are saying that you **like** those talk pages? Hm. Well. To each his/her own opinion... So these "talk" pages are just additional wiki pages that are tied to the main page, with the MediaWiki ability to edit any section of a page by clicking Edit (as opposed to just editing the main page). Which we don't have, and probably won't easily get. But I personally don't really think the discussions there are easier to follow than threaded comments? I see the point about having sections, but it's not all that easy to follow who said what and what was the reply to what, in my opinion.

RE #15 - We are currently proposing *not* having maintainers for wiki sections, just *moderators* (people who can settle disputes and monitor/deal with spam). Section maintainers for the curated docs is quite likely to make sense. And "promoting" Wiki sections to curated is also likely (for instance, I think we would want to promote the install and upgrade guides, or at least parts of them). But possibly the process will be more like copy and paste and adapt than just waving a magic wand and saying "this is now curated". Especially if we adopt some DITA ideas for the curated docs (although that would take *considerable* work on the content and meta-data to adapt content we have now into being more DITA-like). Anyway, let's not discuss the curated docs here, that will be a separate issue.

RE #15 - building it now in D7 - do you mean the wiki? I don't see any features mentioned here that we can't just do on the current d.o? If you're not talking about the wiki, let's not discuss it here. :)

Dries’s picture

Assigned: Dries » Unassigned

De-emphasize the handbook and turning it into a wiki sounds like a good approach/idea: go for it! :)

Thanks for running this by me.

silverwing’s picture

46.48 KB
75.06 KB
49.75 KB
54.03 KB

re#12 By "taxonomy based" I basically want to not use a book hierarchy at all and use alphabetized lists for taxonomy terms/Views instead. (Completely opposite of what we currently use for docs.)

Attached are some mock-ups for this.

arianek’s picture

123.7 KB

It's a bit of an offshoot, but I'm open to the idea of the curated docs being a "promoted" set of wiki pages... the only issue is that doesn't help quality control them and will still require an immense amount of maintenance...

As far as facets/filters/taxonomy - I wouldn't want taxo to be the only way to browse, but it's definitely useful to have a topic taxo. It'd be wonderful to have faceted search on the current terms (audience, version, etc), and I think that would be feasible (with infra's ok). BUT and correct me if I'm wrong, I don't feel like faceted search is super compatible with the conditional text, ie. it's either or. If we have facets then we are sorting based on content taxos/fields. If we have conditional text then all the content is on a single node, and we set what pieces of the content we want to see.

Anyhow, I am no professional wireframer, but just wanted to get some things down visually, and put some ideas from the original redesign for the docs pages (noted as a "Wiki-like documentation article page" on the redesign prototypes list.) and from the Plone docs which I think have some really fantastic features eg.

There is a long way to go yet, but I thought it was worth starting to imagine how this would look - please constructively criticize, but focus on the matters at hand and not my wireframing prowess. ;)

arianek’s picture

If anyone wants a copy of the graffle file, let me know happy to share if you want to work off it (not an allowed file extension here).

Itangalo’s picture

#16: Yes, the proposal is to not have wiki section maintainers – that's why I posted that comment. :-P But I see that there is a point in not adding complex permission levels at this point, so I will drop my feature request. For the moment.

#16, again: I don't see anything that can't be built in D6 (or on d.o). I am just eager to build things in D7, and felt like prototyping a wiki with section-based permissions.

jn2’s picture

#16 regarding c)

I like the headings, which create separate issues without an issue queue, and I like that those talk pages get more information in less screen space. I wasn't particularly concerned with whether it was easier to tell who was replying to whom.

Whether I personally like those pages, though, is really irrelevant. Maybe I didn't make the right point in my posts #6 and #14. MediaWiki format is what people expect from a wiki. If you call it a wiki, but it doesn't look like what people expect, they won't relate to it as a wiki. Maybe completely fulfilling people's expectations for a wiki won't be feasible, but getting as close as possible might be the key to getting people engaged, seeing it as a wiki where people work together to resolve issues with the docs, rather than comments where people expect to have more general conversations.

jhodgdon’s picture

RE #19 wireframe -- cool!

I have a few concerns about the drop-down menu nav idea:
a) It doesn't give you a visual representation of where you are in the book without clicking.
b) If the drop-down contains the entire book, it's huge -- might be a bit difficult to manipulate and navigate. I'm not sure how that would be for a non-visual user to navigate -- would the screen reader start reading at the top of the list even though a visual user would probably see the current item highlighted? If so, that wouldn't be good... but I guess they would have that same problem in the current outline sidebar nav, wouldn't they... OK, drop (b) but it's worth thinking about.

Question on #19 - are you thinking of a tag taxonomy rather than a more formal one? That is actually probably a good idea, especially if we also have a module nodereference (as is currently being worked on).

Other comments on #19:
- I am assuming we want to keep the Drupal version and audience taxonomies and put them in the right sidebar, too? I think they are useful. Also the page status?
- I think the project noderef should go in the right sidebar too.
- I like the idea from #18 of having an "add a tag" button next to the tags, if we can figure out how to do it (or at least some text saying "Edit the page to add a tag" or something like that -- maybe "Edit the page to update any of this information"?)
- Maybe some colors or a separator line on the sidebar would help to highlight the meta-information about this particular page vs. the meta-information about the wiki as a whole?
- I really like the "You are browsing the site building section of the community wiki" at the top.
- And the more I look at it, the more I like the drop-down menu navigation idea in place of displaying the entire outline.

jhodgdon’s picture

RE #22 - So that's a good question: what do people really expect when they see the word "wiki"? Here are some ideas based on some wikis I have used (not all MediaWiki):
a) Non-HTML (e.g., Markdown) formatting
b) Ability to edit parts of pages as opposed to only the whole thing
c) Anyone can edit it, community written
d) Automatic page-level tables of contents based on headers within the page
e) Ability to search and follow links, but not necessarily an outline/hierarchy
f) Multiple languages (translations of each page)

I don't know that the format of the "talk" page is essential, or even the presence of the "talk" page -- I've seen plenty of wiki setups that didn't have that feature at all. I do see what you're saying about the compact format... but there are advantages of the threaded comment way of doing it too, I think?

arianek’s picture

I have so many replies and want to update the wireframe but it'll have to wait till tonight! Stay tuned... ;)

arianek’s picture

709.2 KB

Experimenting and incorporating more feedback (excuse the ugly replication of buttons and such...) - the only "fancy" new feature I added was the keyword tagging (Flickr style), I'm not sure how we'd build that, and have otherwise tried to keep the fancy/new to a minimum so it's more likely this will happen. We can add more and fine tune once the main changes are done! (Pardon me while I agile...)

V2: Wiki

jhodgdon’s picture

#26 - Love it!

A few thoughts (at the level of details, refinements, and bikeshedding now, yippee!!!!):
- If we can't have "add a new tag", then we can just have some text saying "Edit to add a new tag" or something?
- I'm still not sure of the right name for the curated docs. In this mockup, it's "core documentation", but since we use the word "core" in Drupal-land for "not contrib", I think that's confusing... Will need to think of a good name.
- I'd like something more prominent getting across the point of "This is your wiki. Fix it, add to it, edit it".
- I'd like something more prominent getting across the point of "if the taxonomy or other meta-data is wrong, clicking edit is how to fix it". We know that, but new people seeing the page may not get it.
- The "if there's a problem" section says something about "browse existing threads below", but they aren't below (they are listed to the left and fully on a different tab).
- I'm not clear on the distinction between the content-related discussions that should happen on the page and the discussions that should happen in the forums/IRC, from reading that paragraph... or maybe in general. It seems like we are trying to encourage discussions about the correctness/completeness of the content to happen on the page, and discussions of how to use the content (i.e., support) on the forums/IRC? Still not sure about this, or how to get it across in a short zippy point. And I'm not sure if people will read it -- maybe put it at the top of the Discussions box at the bottom, and on top of the Discussions tab too?

Regarding the "prominent points" above, maybe we could move the "If there's a problem" paragraph up to the top (of the main content section? or of the sidebar? It could be in a yellow box at the top of the page maybe?), and have it say something like:

This is your Drupal Community Documentation Wiki. If there's a problem with the content of this page or the information in the sidebar, click "Edit" to fix it.

Things I see on this mockup that will need to be built and/or existing modules installed (which will need to become issues eventually):
- Discussions block at bottom
- Discuss tab at top
- Doc nav tabs at top (API, Community Wiki, Core Documentation)
- Drop-down book navigation on right sidebar
- Moving all meta-data to sidebar in general (instead of yellow box)
- Authoring info section (original and other contributors)
- Levels and Tags taxonomies
- Related projects (this is already an in-progress issue)
- Ability to add new tag without editing the page, if possible

jhodgdon’s picture

One question, regarding Discussions:

Just occurred to me... Are we planning to use straight Comments (attached to the page), or Forums with a node reference?

batigolix’s picture

I see some problems with the mockup:

- It reflects too much our internal discussion about turning the handbook into a wiki. The fact that you can edit and discuss are repeated too often in buttons and descriptions in the left column. Our concern about not succeeding in converting the community into DIY documenters should not be that clear.

- The left column is very long and bursting with meta information. Many current handbook pages (I keep calling them so because they use the book outline) are placeholders or small, almost empty, higher level pages that were created just as containers for child pages. Imagine such almost empty page with a huge amount of meta data. It would be kind of silly. As an example I like t point to the rather sad looking documentation pages of the brand new Workbench module: e.g., and . This is the state the current handbook is in and that we have to deal with and keep in mind when switching to a community wiki

- The mockup doesn't show the parent and child pages of the wiki page. The entire current Drupal handbook is structured according to hierachical book outlines. Without showing the higher and lower levels pages of the current page, many of its meaning is lost. I do agree that at some point we should get rid of this hierachical structure, but by just omitting it in the layout of the new wiki page, many pages will become incomprehensible

jhodgdon’s picture

RE the first point on #29 - I think that people don't understand they can click Edit. Even among those who come to Doc sprints at the DrupalCons, that's the biggest hurdle -- convincing them "Yes, it's OK, you can edit that page". I mean, really we have a wiki now (at least by some definitions of the word). Yet people do not edit the docs, even though they can, out of fear. So I think we *do* need to stress that people can edit. My suggestion is in #27 - a yellow box at the top of each page saying:

This is your Drupal Community Documentation Wiki. If there's a problem with the content of this page or the information in the sidebar, click "Edit" to fix it.

RE second point in #29 - What of the meta-data would you suggest leaving out, or do you just think it should be somewhere else? (I'm assuming you mean the right column not the left column). I think if we do the above yellow box, we can leave some of the stuff out of the right column (the parts about how to edit anyway).

RE third point of #29 - The point is to use a compact drop-down (which would show the hierarchy once you clicked on it to open it up) instead of the full outline nav we have now. We can debate the merits of it though... And if you're concerned about the length of the right sidebar, putting the outline nav back would make it even longer.

batigolix’s picture

Regarding #30: yes, the ability to edit the page must be stressed, but not repeated that often. a yellow box on top of the page might do the trick

I would place the important meta information back on top of the page so that the reader is aware. I think the page status and Drupal version are important: they help the reader to decide if he must continue reading. Audience and level can stay in the right column. Authors and dates can stay in the right column, or even be omitted as that info can easily found on a revisions page. I would omit or at least shorten the information about the support and license.

I don't know how to solve the problem of showing the outline. I'm less concerned about the book outline in the right column and yes, the dropdown is a compact solution for navigation. I'm more worried about child pages links below the body. Many pages in the current system will loose their meaning if those child page links are left out.

lisarex’s picture

As for the outline and navigation, this is the approach we took a developer site I worked on. It's a good compromise between reducing the amount of navigation on screen and accessibility (I would not recommend drop down as navigation around the documentation).

Uploaded with Skitch!
arianek’s picture

So much great feedback! Ok I have questions before I try and incorporate that all into another revision.

How much can we expect as far as infra support - ie. if we wanted to do some kind of javascript menu, or the fancy keyword tags... is that possible or will it really hold things up? Also new design elements - allowed? Or does it need to be vetted somehow cause of the redesign?

I've been trying to really stick to things that will be easy-ish to implement, and hence not getting overly creative.

webchick’s picture

I think Neil Drumm should really be brought into this discussion. While I'm +1 on the general concept, the big question in my mind is if this goes on or If, I get nervous about adding any more module dependencies, since one of the goals we're trying to shoot for is a upgrade to D7 by D7's first birthday (Jan 2012). If, then it should probably be done in D7 from the start, but that'd give a lot more flexibility as to what modules could be installed. Neil's the one to make that call, IMO.

webchick’s picture

...and Gerhard / killes as well. (See: Process for getting changes deployed on

silverwing’s picture

Some quick thoughts on moving to a subdomain in D7:

  • Identity - you will know you're in a wiki, and what you can do.
  • We can address the specific needs that are identified (have we identified them?)
  • Tools - we get to use the cool tools that aren't allowed on d.o. - like 5star(or thumbs up/down), Flag for bookmarks,
  • It's a fresh start - we don't have to inherit any perceived problems.


  • Importing content - there's a lot to import - and do we redirect?
  • Lack of continuity between wiki.d.o and d.o - i.e. if we allow bookmarks on wiki, can we see them from our d.o profile page? (Thinking about it, I'm sure we can - as we do for MyYour Groups)
  • User (and contributor) buy-in - would enough be willing to make their doc pages in the wiki for modules/themes?
  • Needs an issue queue and moderators (not really a con, just a fact).
Sree’s picture

34. with D7 would be a good choice

jhodgdon’s picture

21.08 KB

RE #36 - We are actually talking about eliminating the issue queue for the Wiki (aside from perhaps reporting spam).

For me, putting it on a D7 seems like a massive undertaking -- just think of all the links we would need to redirect, content to import, etc. I can't imagine taking it on, and for that reason alone, I am inclined to leave it where it is. I don't think we are really talking about adding much in the way of modules -- just a few more tweaks in the drupalorg module, right?


RE: Navigation... I'm not sure I understand how Lisa's suggestion in #32 would work -- does it show the same parts of the outline that we are showing now, but formatted differently? That's what it looks like. So I don't see how it saves space?

So. When the redesign was launched (or maybe it was just before launch, I don't remember for sure), we lost the list of child pages that is at the bottom of each Book page (see attached image). It was a problem, and we added it back in. I think that we need to keep that on the Wiki... I don't think MediaWiki (at least as implemented on Wikipedia and other sites where I've seen it) supports outlines at all, but we have one in our Wiki, and I think we need to display at least the child pages (and an "add child page" link) on each page.


RE: Meta-data - It sounds like Batgolix is advocating pretty much leaving the yellow box meta-data where it is now at the top of the page, thereby freeing up some space on the sidebar after all (which we can then leave for navigation as it was). Maybe this would be the easiest solution? Just add the "related modules" meta-data (which like the other stuff is fairly important) to the current yellow box -- minimal changes required -- and call it good?

If we do move it all to the sidebar, maybe we can highlight the important stuff with yellow so it stands out more? I guess, thinking about it, I'm not sure why the suggestion is to move it anyway...

dasjo’s picture

i think "making documentation a wiki" is a good idea as it gives the ability to redesign our documentation effort.
on the other hand i believe that we should not believe in the "wiki approach" to solve all our problems, it is just a marketing teaser that might help us reach that goal :)

personally, i would be in favor of combining the "usability aspects" of the wiki-approach (getting more people involved, motivating them to edit and update things) with "structural benefits" that we can have by integrating with the current project/version/tags/issue queue infrastructure. i think that the main problem right now is, that documentation gets out of sync with the project development and therefore we should always keep in mind how to integrate with the well-established issue queue workflow, from my perspective.

long-term target: better, well-integrated documentation infrastructure
short-term approach: a demo like as a place to build the new components in an agile way

jhodgdon’s picture

Just to clarify, the main problem that "making the doc into a wiki" will solve is burnout and the unrealistic expectations of the docs team leadership. I don't really think it is likely to improve the quality of that documentation. It will just let the docs team leadership focus on some other documentation that will (hopefully) be of higher quality.

Also, just to clarify: the current doc on *is* already a wiki -- in the sense that everyone can edit most of the pages and it's maintained by the community. #24 listed some things we might do to make it even more wiki-like, but I don't know that we're actually going to implement any/many of them, beyond making all the pages editable (including the ones with images) and making it clearer that the community maintains the wiki (with a prominent header, name, etc.).

drumm’s picture

What exactly is a "real wiki"? Are we going to have CamelCase links and piles of punctuation to do formatting? Wiki means so many different details for different systems, and doesn't tell end users that this is still documentation. +1 to improving UI, but -1 to the word wiki.

It would be good to see the individual improvements each get their own issue and listed at

wfx’s picture

If we are still looking for inspiration the Blender 3D folks just redid their Wiki and it looks really awesome

It sounds like a radical change in the way the current wiki works (which would involve a lot of new modules) isn't likely to happen right now because of D7 upgrade concerns. However, could we just make some changes on the theme layer to make our current wiki look more Wiki-like? Give the book pages a fluid layout (occupies 100% of the screen), move the navigation block to the left, ect. I know this isn't the optimal change everyone was hoping for but any change would be an improvement. The goal here is to make Docs sustainable and that means making our Wiki look more Wiki-like to new contributors. To me, theme changes are the quickest solution which wouldn't hamper later upgrades.

jhodgdon’s picture

A lot of other wikis do not have book navigation. We have book navigation, and it's a prominent part of the way our documentation/wiki/whatever-we-call-it functions. We really don't want to get rid of it.

Also, research has shown (I think? read it somewhere many years ago) that fluid 100% layouts are harder to read if you are trying to actually read text on a page (lines are too long for most people to scan), so why would we want to go to that -- I don't think it's an improvement.

Regarding #41 - I don't think we are advocating markdown formatting and things like that right now anyway. Do you have a suggestion for something else to call this other than "wiki", which will get across the point (concisely) that it is documentation that the community is maintaining and is encouraged to edit, without also implying markdown formatting and some of the other Wiki features that we probably don't want to add?

Also, yes, once we decide on what changes we want to make, we will of course file issues. We're still in the bikeshedding stage at this point...

Everett Zufelt’s picture

Re: line lengths -

Old article, but the concept is true.

MGParisi’s picture

I want to see the death of the BOOK! Well not quite, but limit its use to some very specific situations. Most of the documents should simply be linked via a multiple tagging system with a good search version. Such a tagging system would have to be thought out...

Information is simply not stored in a hierarchical structure. Managing the books navigation is near impossible and the overall document navigation is rather useless. In fact I find docs using Google, not the sites navigation:(

Edit - Also with the redesign of module pages, every module should have a book and it should be linked to the navigation of that module. Module centric documentation has been a goal of mine for a very long time. The documentation would include tagging for that modules version. Therefor as Modules Grow older they would not be overwritten in a way that would eliminate the validity of the earlier versions documentation...

jhodgdon’s picture

Thanks Everett. I suppose that line width doesn't matter much to you personally, so it's a bit ironic that you found and posted that link. :)

jhodgdon’s picture

RE #45 - I think we need some hierarchy ability -- at least the ability to make an outline in a section of the handbook. And we have to keep in mind that good technical docs (in general) should be organized by task, not by Drupal module. Which is what the current overall outline tries to accomplish... whether it accomplishes it or not is another question. It does serve some purpose -- I personally use the outline to find certain pages... but agreed that it's a bit of a beast.

Having a better way to find docs of interest would be good, but I don't know that it's something we can build today. Ariane's screen shots above had keyword tags, and that might be a good start, but adding this is not going to magically tag everything either, so it will be a while before the tags become useful.

(another comment coming shortly)

jhodgdon’s picture


There are many ideas floating around.

Let's step back a moment, and focus on what we really need in order to make the current into truly community-maintained documentation (which is the main goal here), and separate that from ideas about other infrastructure improvements (which we can deal with in the future and on separate issues) and from what a "wiki" would be.

Here are my thoughts:

a) We need something more prominent at the top of each page, encouraging everyone to add to and edit the docs. Such as a bright yellow box saying "This is your Drupal Community Documentation. If there's a problem with the content of this page or the information in the sidebar, click "Edit" to fix it." (if we don't move some meta information to the sidebar, remove the "or the information in the sidebar")

b) We need to remove the expectation that there is a Docs Team who maintains the documentation, and replace it with the expectation that the community as a whole maintains the doc. The yellow box proposed above will help. We also need to edit the sidebar that is on each docs page, and the Contribute to Docs section in general.

c) We need to open up all/most pages for editing. This is waiting on #528682: Allow inline images to be posted to project pages, docs pages, and comments without any special permissions.

d) We might want to move the comments to a separate "discussion" tab. I'm not sure if this is necessary for deployment or is a future fix? Other ideas have also been suggested, such as making the discussion tab be a page rather than threaded comments. Those are definitely future-material IMO (needs thought to figure out how to deploy).

e) We need to change the header nav on Doc pages to say "community documentation" (or community wiki or something) to reinforce (a) and (b).

f) We need to discourage use of the Docs issue queue, in favor of encouraging people to edit page status and add discussion. This will require editing some Contribute to Docs pages, and removing existing text on sidebar that encourages filing issues. We also need to figure out what to do with the existing docs issues. My feeling is that:
- issues asking for new docs to be written can be closed as "won't fix" with a comment saying we aren't using the issue queue for this any more.
- issues pointing out problems in pages will have to be gone through manually (maybe in a sprint we can set up for the month of November or something?). For each one that is open, the page status should be changed to something appropriate, and a comment added to the page pointing to the issue and saying 'this has been identified as needing to be fixed', and then closed as "duplicate" with a comment saying we aren't using the issue queue for this any more. I think we can make a process for this that sprinters can deal with.

So. I think if this is the limit to what we are doing *right now*, we are not asking for lots of new modules or a huge amount of infrastructure change, and it seems rather manageable. Thoughts? Did I miss anything that is hugely necessary for right now, to accomplish the main goals of making this community-maintained docs?

arianek’s picture

146.1 KB

As per usual, Jennifer was reading my mind while I was chipping away at the mockup, and already addressed a lot of the things I was thinking about.

I lost track of which comments all these were in reference to, but briefly...

- i moved the instructions in the yellow box - emphasizing editability and community ownership is important. added an "x" in the corner to close the box as a "nice to have" or later add-on, so those who know the drill can hide the text.
- kept the metadata in the sidebar (i think it helps to keep the page more readable/decluttered and the info is easy to find if you need it)
- discussions = noderef'd forum threads (still aligned with the kill comments initiative)
- not worried about small pages, we're not going to solve that piece in this round
- added child pages outline back in at bottom (i was trying to declutter the page)
- did not change menu as i don't think there is space for a full or expanding one with this design. if it's a must have, will need to overhaul this mockup.
- did not try a 100% layout as it strays far from the d.o theme and makes it difficult to place all the needed info on the page.
- markdown is not on the table right this second - need to keep features to a minimum to keep this implementable, then can do more improvements.
- ditto for moving away from book. let's maybe look at that when we come to the d7 migration - the docs are hierarchical by nature, it doesn't make sense to try and flatten them. but yes, definitely link to module/project and tags - it's the crossreferencing that's important.
- toned down the "wiki" language and focused on small UI/text changes to encourage editing - hopefully along with a marketing plan, we can get this change in mentality across to the rest of the community.

Also, I talked to drumm earlier - in addition to the caution about "wiki" language, he let me know that it would be desirable to stay away from making a subdomain or delving into D7. Staying on the main d.o will keep maintenance the most efficient (and that's important cause we want to keep infra team happy!). He added that as long as modules are well maintained and have a D7 upgrade path (for when d.o gets upgraded), that within reason it shouldn't be a big issue getting them added.

All that said, I decided to just do another incremental revision to the wireframe incorporating some of the feedback above... tada:

arianek’s picture

ps. Just realizing that the text above the dropdown menu should probably read something like: "You are currently browsing the [Site building guide]" now.

chasehrlich’s picture

First post here...know nothing about Drupal other than what I saw on a few Youtube videos.
But the idea of a wiki-like interface to Drupal is nothing new and I am looking for exactly that.
I found this ancient but interesting tidbits: ... no longer supported as of 2009/07/25
Is this perhaps time for the documentation team for Drupal to take on the task of reviving this module?

jhodgdon’s picture

Title: Make the current Documentation on into a real Wiki » Make it more clear that the Documentation on is community maintained

RE #51 @chasehrlich - Sorry, this discussion is about changing our documentation process and management, not really about making a wiki-like interface (in spite of the title, which I'm now changing). If you would like to revive the Liquid module, please read this page about the abandoned module process:

jhodgdon’s picture

RE #49 - YES!!!

I would make a few very small tweaks:

a) On the top of the right sidebar, change text to: "You are now browsing the (link)Site Building Guide(endlink) section of the (link)Community Documentation(endlink)". [change: documentation -> community documentation]

b) In the top yellow box, change text to: "... If there is a problem with the content, keywords, or other information on this page... start a new discussion. Be sure to edit and update the page status!" [making it clearer that the meta-data is included in 'content', and that you need to edit to update the status, which I think could be confusing.]

Inventory of what we would need to do (I think) to accomplish #49:

  1. Yellow box at top (drupalorg module, easy)
  2. Move meta-info to sidebar and tweak sidebar block wordings (drupalorg module I think, easy)
  3. Book nav outline -> drop-down (small custom module needed, add to drupalorg project)
  4. Nav at top - change Documentation to Community Documentation (drupalorg module, easy)
  5. New taxonomies for Book pages: Level, Keywords (presumably this is admin UI?)
  6. Project reference for Book pages (in progress on #733908: Add noderef field for project to doc pages)
  7. Book reference for Forums (issue: #1027608: Use forum to make Discussion tab/block for Book pages - will need to recruit someone to do this, not difficult)
  8. Revive existing dead/deprecated Documentation forum (admin UI)
  9. Tab to display the forums related to a book, and block to display most recent discussions (views -> feature export -> drupalorg module, shouldn't be hard?, should be part of that other issue 1027608 or we can make it part of that other issue if not)
  10. Convert existing page comments into forum posts (maybe we can do this with a database query in a drupalorg.install update function???? I think it should be possible? Then turn off book page comments?)
  11. Convert existing issues in doc project into forum posts with appropriate book refs (this is a manual process - sprint? see letter (f) in comment #48 above).

This seems rather manageable. I am +1 on the mockup in #49 as our initial step (with the small tweaks above). Anyone else have an opinion on adopting this as a sufficient first step to move forward on this?

If we adopt this as our proposal, I will update the issue summary, file/update a few issues, and recruit people to get the changes made!!!

jhodgdon’s picture

Oh, and we'll also need to edit the Contribute to Docs section. :)

EDIT: And I forgot

We need to open up all/most pages for editing. This is waiting on #528682: Allow inline images to be posted to project pages, docs pages, and comments without any special permissions.

silverwing’s picture

+1 to #49 to get things rolling

wfx’s picture

#49 @arianek I like your new mockup, well done. +1 from me as well
The "Community Documentation" title is a nice touch. It really hits home who writes and maintains the content.

Regarding my earlier suggestion for a 100% layout, for the record I hate liquid layout, I was only suggesting it because that seems to be what a lot of Wikis do use and thought it might promote more participation. It was a bad idea, it does reduce readability.

@jhodgdon I have some ideas on redesigning the main docs landing page. Should I post my mockup here or on the Groups thread? Don't want to muddy the issue thread.

jhodgdon’s picture

wfx: We should probably start a new issue for follow-ups to this (infra and other improvements to the community docs)... Actually, I'll do that now:
#1287784: Follow-ups to improve the community docs

And I'll update the issue summary here to point to that issue.

jn2’s picture

#49 Love the wireframe! And #53 is a very clear and concrete proposal on how to get it done.

The main points here seem to be to eliminate the issue queue and get people to edit the pages if needed. This does both. The discussion tab makes the changes noticeable enough that people might change their behavior. No new modules, all on d.o, all with current docs.

Big +1.

jhodgdon’s picture

"no new modules"... well, actually there will be a couple of small-ish additions to drupalorg (features -> modules, and also the right sidebar nav block).

jhodgdon’s picture

It looks to me as though most of the active participants in this thread are for the proposal in #49/53.

Also, Angie (webchick) and Dries both endorsed the general idea, with the caveat (webchick) that we don't want to introduce a lot of new functionality/modules to d.o (which I think we're fine on with this proposal). Neil (drumm) commented that we shouldn't use the word wiki, and that seems reasonable, since it doesn't quite meet the expectations people have when they see "wiki" -- and the current proposal doesn't say "wiki".

So I'm not seeing any counter-arguments or objections to #49/53... I think we should adopt it as a working proposal (small refinements can be worked out on the individual issues). I'm going to go ahead and edit the issue summary now and file some additional issues to work out the details.

jhodgdon’s picture

Issue summary: View changes

update summary

jhodgdon’s picture

Whew! Massive issue summary edit, and several issues filed. If we're decided (are we?), the next step will be to recruit people to work on the infra/dev issues (which I would do on

Should I go ahead and recruit - Ariane? Are we decided for sure?

jhodgdon’s picture

Title: Make it more clear that the Documentation on is community maintained » Make it more clear that the current Documentation on is community maintained

Minor title tweak. :)

arianek’s picture

I'm on board - I'll try and get a final version posted over the weekend, since there were a few more tweaks needed.

jhodgdon’s picture

I'm not sure a new screen shot is necessary -- I think we're OK with what we have. I'll post the issues on the recruiting builders thread on g.d.o then!

jhodgdon’s picture

Talking to silverwing just now in IRC - we realized we need to add one thing to the proposal: a link to contact the moderators and/or report spam, if we are going to have a moderation/spam patrol for the Community Docs.

Should this go in the top yellow box?

Maybe a line saying:

If there is a dispute that needs moderating or spam to report, (link)file a moderation issue(endlink).

The link would file an issue with:

project: documentation
component: community docs moderation
subject: Community docs moderation on (URL)
The page (URL) needs moderation.
Describe why here:

Issues can already accept these fields. See the links at the bottom of pages for examples.

Thoughts? Top yellow box or sidebar? Tweaks on the text?

yoroy’s picture

I'm unsure if this message needs to be communicated so prominently. Current proposal pushes the actual content at least 5 lines down. Should it be shown *above* the actual content in the first place? Maybe it can be shown below the content, as a call to action *after* digesting the content itself? Somebody who has read the content might be more susceptible to this message.

A question: there's a closing 'X' in the mockup. If I close the message, will it never be shown again? What is the intended behaviour.

I don't question the need to communicate this message, but I worry that this design might be going overboard edging towards annoying instead of inviting.

jn2’s picture

#65: Maybe separate the two.

On the discussion page:
If there is a dispute that needs moderating, (link)file a moderation issue(endlink).

At the bottom of the text:
Is this spam? (link)File a moderation issue(endlink).

Or something like that. If there's a dispute, it's likely happening in the discussion area. And as yoroy points out (#66), you'll be more likely to respond to the spam question and know the answer after you've read the content.

The issue content looks good.

arianek’s picture

Status: Active » Needs review
148.68 KB

Had to make a few more tweaks (it's the project manager in me...) just so we have a clear template...


- updated the text at the top of the sidebar (before the menu)
- left yellow box text at top but cut down the text to the essentials - i really didn't like how it looked at the bottom (i can post a mock if people want)
- added moderation info at very bottom of content above the book nav (we may *also* want this on the discussion pages as jn2 noted - not sure how much we want to delve into changes in forums)
- removed the 'x' in the yellow box to simplify matters

jn2’s picture

Looks good to me. Adding "Inappropriate content" to the text at the bottom is a good addition.

pillarsdotnet’s picture

In addition to a TOC, it would be nice to have a way to flag keywords (and their synonyms) for inclusion in an index. For example:

Input text
With permission, users can post messages on other users' <cite>profiles</cite>, <cite>groups</cite>, and nearly anywhere else.
Rendered output
With permission, users can post message on other users' <a id="profile_1" href="/node/999999#profile_99">profile</a>, <a id="og_1" href="/node/999999#og_99">groups</a>, and nearly anywhere else.
Index entry
<dt><a id="group">Group</a></dt>
<dd>See <a href="/node/999999#og">Organic group</a></dd>
<dt><a id="og">Organic group</a></dt>
<dd><a id="og_99" href="/node/123456#og_1">Facebook-style statuses</a></dd>
<dt><a id="profile">Profile</a></dt>
<dd><a id="profile_99" href="/node/123456#profiles_1">Facebook-style statuses</a></dd>

In this example, the <cite> tag is changed by the text input filter into an index link. It would probably be more straightforward to use <a rel="index">, but I like the idea of making the <cite> tag actually do something.

Also, group is a synonym for og, and the plural of any keyword is automatically a synonym for its default singular form. Of course, there would have to be a mechanism for registering indexed keywords and their synonyms.

pillarsdotnet’s picture

Issue summary: View changes

Concrete proposal from comments #49/53 added, major revision

jhodgdon’s picture

#70/pillarsdotnet: That looks like a follow-up idea, not a "we must have this to launch" idea. Please post to #1287784: Follow-ups to improve the community docs

#68 - Looks good. I've posted this updated mockup to the issue summary and the related issues.

Bojhan’s picture

A quick visual review, looking at it from an outsider (not familiar with this issue) it looks like we are trying to solve a multitude of problems and doing so by adding more visual heavy elements (which distract the reader from the content).


I am concerned that the goal of this issue, is inherently difficult to get across. I would be more concerend with minimzing the additional meta information we need to give to our audience. The sidebar for example could be better used for book navigation, but could also hold the current information far better with some alignment, headers and color.

arianek’s picture

Hi Bojhan, thanks for the input.

Just to note - your first two concerns about the 3 page titles and yellow "error looking" box are part of the *existing* design. Eg. below from

1) Triple titles: I have no ties to the triple page title, I was just trying not to change the overall design which was intact from the redesign - if you have suggestions here of how to change it but maintain the actual page title and the API/community docs toggle, we're all ears!

2) Error style block: The "yellow error" style has been used for a long time for the metadata - I would also be happy to use different styling on this instruction block, but I do think that it is important to have it there (or somewhere on the page where it's fairly visible). Suggestions?

3) As for the the sidebar info/style and metadata: This part I don't think should be changed (much) from what's in the mockup. The dropdown menu is easy to navigate and it's obvious what's going on as soon as you click on it. If you know another way to show a massive menu in such a condensed format, I think we'd all like to see other options.

But the metadata, keywords, etc. are VERY critical to these revisions - they are what people have been asking for again and again: clear indexing by skill level, version number, and audience; clear references to the related projects; more focus on the authors of the content; and finally the keywords. The keywords are a particularly necessary part because the documentation is organized in a task based fashion with absolutely no cross-referencing by *topic*. The keywords will finally allow users to easily find other content related to what they're looking at without having to go back to a google search for example. Even multiple book outlines would not be able to accomplish this.

But again, if you have some better ideas, or suggestions for how to lay this info out in a more visually appealing way, please let us know what you would suggest. I have tried to stay very strictly to the existing styles from the redesign, and not introduce new elements as much as possible, which is why I did not introduce new colours, etc.

dasjo’s picture

with regards to the sidebar dropdown menu as a replacement for currently displaying the whole navigation tree i'm a bit concerned:
i believe it's a good idea, that we try to reduce complexity but if documentation is organized hierarchically i would like to know where i am at right now.
so how would that look like for the facebook style statuses example used for the mockup discussed in #72? refer to for the current status

Community Documentation
- Site Building Guide
-- Social Networking and Collaboration
--- Facebook-style Statuses

i think this" breadcrumb info" should be there, unless documentation was to be organized and navigated primarily by tags.

arianek’s picture

Yep - try out the one here for an idea of how it may look.

Bojhan’s picture

1) Yes, this is a bluecheese problem. Its an existing problem. Can you explain me however what the community/api toggle is about?

2) Yes, this is a bluecheese problem. It is made worse though, by how you layout the message. The current one looks far less like a error message because the information is layed out very differently, in your proposal this is different and looks more like an error message. I never really got the purpose of the message, because I think its most likely ineffective - do we have any data messages like this create more edits? I would ideally place this message in the sidebar.

3) Wait, does this replace the book navigation? Please tell me I am wrong. Because that's a really bad navigation model.

What will help you design the sidebar better, is to organize the importance of elements. Currently visually "to which version it applies" is as important as "when the original post was made". To design this better make a list and assign points/percentage, to the importance of each element on this page. With that information its way easier for me, but also yourself and others to redesign.

I know when I criticize, the first feedback I get is mockup something new :) But I would love to first get a better understanding and help you do a few iterations before I jump in. Don't be afraid to change the visual look of these pages, the style guides are not set in stone and did not account for all this additional information.

wfx’s picture

Have to admit, until now I couldn't quite wrap my brain around the "Facebook style statuses" part of the design. That made more sense to me when it seemed like we were moving toward overhauling everything and getting away from Book entirely and using something else. My not understanding this part of the new proposed UI is why I kept the whole navigation tree for the collapsing block in my follow-up Redesigning Docs landing page. Your link to the Plone doc does help to show how your design would work. I obviously didn't drill down far enough into the Plone documentation to see that drop down nav in action.

jn2’s picture

Maybe this looks less like an error message for the yellow box:

Incorrect/incomplete information?
Edit the page Want to discuss?
Browse current discussions -
Create new discussion Need support?
Support forums -
IRC #drupal-support

Don't know how well that will fit in the box, but maybe something like that?

jhodgdon’s picture

RE #76 -

1) The tabs -- Community Documentation = the current "Docs home" tab on docs pages, which we are renaming "Community Documentation". API is the current link to, which as Ariane pointed out above in #73, is already on the docs pages. So this is exactly the same as the tabs on current Docs pages, except "Docs home" becomes "Community Documentation". And eventually there will also be a "User Guide" or "Official Help" tab (or whatever we call the curated docs -- see #1291058: Discussion: Make a curated docs section/system).

2) We already have information in the sidebar saying "please edit the page" and no one feels empowered to do so (based on the fact they are much more likely to comment on a page saying there is an error vs. just going ahead and editing, and based on talking to people at DrupalCon sprints who say "Is it OK for me to edit the page?"). So. Yes, we could do some usability tests on proposed texts, colors, placements, etc. Let's think about this -- can we make a quick usability test happen? Can we make a few mockups to test (colors, text, fonts, etc.)? We really need to do something to get across this point prominently:

This is the Drupal Community Documentation. You are part of the community. Please edit and add to it!

(not suggesting those exact words)

3) Yes, see link arianek posted in #75. The current book nav is very long and unwieldy. We are keeping the child page list at the bottom of pages though.

But you are right, we could make the information in the sidebar better organized for priority. Let's do that. We have time. We're currently not making any of the sidebar/header changes until we get a couple of other infra things done (like the discussion page), so there is definitely time for better mockups, usability testing, and tweaking. :)

JuliaKM’s picture

I really like the direction of #68 but find the page a bit challenging to quickly navigate.

It seems to me that there are three types of content on the page:

  • the wiki text (info on Facebook-style statuses)
  • opportunities to take action (Flag, Edit, Discuss)
  • metadata (page status, content info, keywords, authoring info)

With the current setup, I need to continuously evaluate whether I am looking at wiki text, an opportunity to act, or metadata. As a user, the most critical information for me to see on the page is the page status and actual page content. However, what I really want to know before I start reading the content is whether the page is crazy out-of-date or includes dangerous code.

I'd recommend making the following changes:

  1. Move the content from the yellow box to the right sidebar.
  2. Add a conditional style to give the wiki text a red background if there's a big status issue (Insecure Code/Depreciated).
  3. Add a button next to Edit/Revisions/Discuss for Flag and remove Report this Page.
  4. Remove Discussions from the sidebar. There's already a lot of sidebar content and a prominent link to "Discuss this page." Perhaps it's just me, but I find that these types of lists of relevant discussions on d.o. rarely take me where I want to go and often make it hard to get back to where I was before.
  5. Move "Drupal's online documentation is..." to the footer of the page.

Thanks to everyone working on this!

jhodgdon’s picture

Um. We don't have flags. If there is a problem, someone needs to edit the page to change the status. And if it's spam or otherwise needs moderation, they are reporting an issue describing the problem.

But other than that, good thoughts/ideas in #80... Guess we might need another rework, with Julia and Bojhan's ideas...

webchick’s picture

Just a note that we are within a week or two of having Flag module deployed on #34496: [meta] Add Flag module to allow users to subscribe/unsubscribe without posting a comment is getting really close.

JuliaKM’s picture

@jhodgdon: My mistake (although it's awesome that flags will be here soon). I was trying to say that there should be a one word button for "Report this page" instead of having a text block at the bottom of the node.

arianek’s picture

Hi all -

So, I wasn't suggesting Bojhan (or others) try mocking up their own versions just cause I don't want to do it (though I can't mock up every suggested change, obviously) - it's because I am no UI/design pro. At work, I do rough wireframes and then hand them off to the "real" designers... who have a lot more tricks in their toolbox than I do.

If anyone has strong feelings that the version I've been working on is going down the wrong path, and has some design experience, please do post a more concrete (ie. visual) version of what you think should be going on. I'm happy to provide a copy of the Omni Graffle file I've been using (just send me a message through my contact form), or if you don't have that app, try importing the image into a Google Docs Drawing file.

I can only get so far on my own - I don't really know what to do with some of the feedback that's come up since we almost had agreement here!

JuliaKM’s picture

Issue tags: -docs infrastructure
836.49 KB

Here's a new wireframe with my feedback from #80 included. The page status is also now set to "Depreciated" to trigger a red background. I'd propose that the red background only show up when the page status is Depreciated or Insecure Code.

I can do another wireframe to incorporate feedback about the menu style, but I'm not sure what the alternative solution would be. The Plone implementation arianek proposed seems like an improvement over the current menu structure to me.

arianek’s picture

See, this is why mockups help! That is totally not even what I was picturing when you suggested it. :) Thanks Julia.

I could be sold on:

- Adding the "report this page" link at the top instead of bottom (though I don't know if it really needs to be that prominent). If we did, we might need to have slightly different text so that people know to use it only for moderation issues, not content issues.
- Removing discussions from the sidebar (though I think it'd help get people to use it more if they can see some snippets right on the page).

I'm on the fence on:

- The red background. I was thinking we could just still use the little icon in the sidebar like we currently use in the yellow box.
- Moving the copyright info to below the content.

I'm not so keen on:

- Completely removing the instructions/links in the yellow box in comment 68. Is there somewhere else we could put that where people wouldn't just ignore it?

And from Bojhan's comments, I'm still thinking that if it's an option, it might be nice to try and cut down on the triple title - not sure what the rest of you think about that though...?

arianek’s picture

222.07 KB

ps. also I figured out that I can bypass the .graffle file upload issue by zipping it! In case anyone else wants to join in...

jhodgdon’s picture

Issue tags: +docs infrastructure

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.

JuliaKM’s picture

I see what you mean about "Report this page" now being too prominent. What about adding a flag icon with a link for "spam/inappropriate content" once the flag module is live on d.o. that's next to Add new discussion instead?

Is there somewhere else the discussions could go on the page? It just seems like the sidebar is getting pretty long. Then again, if the copyright info is at the bottom, perhaps it doesn't matter as much.

I can see what you mean about the red background being a bit crazy. It would be nice to have something more prominent than the red alert on the right and less prominent than changing all of the background text.
@UX Experts: Thoughts?

I wish there was some way to do o a quick usability test to see how often the yellow box is read when it's in the node section. In particular, it would be cool to do some sort of eye-tracking test.

I agree that the triple title is a bit confusing. Would it work with the existing d.o. style to add breadcrumbs?

So, something like:

Facebook-style statuses
Documentation > Community Documentation

jhodgdon’s picture

RE: too much red - Could we just turn the warning text itself into red, or the background of the warning message for those taxonomies?

Also, next time you attach a screen shot, can it be bigger so if I open it in a new window I can see the details? :)

Flagging is a good idea for reporting spam/inappropriate -- quick and easy. We would then also need to add the flag to the Management page, which is not difficult. Then we could pretty much avoid the issue queue entirely for the Community Docs.

Regarding the triple title... All pages on d.o have this, so I don't think we can really remove it from Docs pages. Once we get the Official/Curated docs section up, we will have "Documentation" as the top-level title, then a row with tabs: Community Docs, API Docs, Official Docs (or something like that), then the page title. I think/hope once the 2nd row becomes three tabs, it will look better than the current two tabs and make more sense? Anyway, we probably can't redesign as noted above, as it is d.o site-wide.

jhodgdon’s picture

Issue tags: +docs infrastructure

One further note on the "3 titles" thing -- that second row that says Community Docs / API Docs should be tabs (as it is on the current d.o site). All we're doing is replacing the words "Docs home" with "Community docs" on the typical docs page (and we'll be adding a new tab for the official/curated help/docs as well).

heather’s picture

Heya, I'm not active much on docs right now, but I do use them. Sorry if someone has made these same comments in other threads.

1. A related issue about the big overhead with stacking page titles and confusing sub-nav: #869936: Subnavigation improvements

2. A big + 1 to "discuss" this page, and putting the talk in the background.

3. And +1 to coloring for a warning status. As long as it is clear. Can the sidebar > Status text be colored with the same background?

4. Sidebar > Content info
Is content info going to leverage faceted search? Would be great if they are links.

5. I am confused by the cross-article navigation.

On this comment by wfx, there are good examples of "top level" items which were collapsible. Are we going to have that kind of model? Top level item > Click to expand to see child options? Maybe that is a better way to handle this.

In this screenshot below...

A. Is the the Sidebar > Dropdown menu going through the whole documentation? Or just within a top level section? If so, how do I go from section to section? I can't imagine what the menu should allow me to do.
B. The sibling pages at the bottom are hidden. It's a Drupal-quirk to me, and often raises more questions than it's worth to have the book navigation at the bottom of a page.

Is it possible to move B to the upper right? Then, the drop down menu could "jump" between top level sections and you don't need the Drop Down Menu To Rule Them All.

cross article navigation
Uploaded with Skitch!
jhodgdon’s picture

The drop-down menu will show the parents, siblings, aunts, uncles, grandchildren, etc. Supposed to work like this site:

lisarex’s picture

Still not sure a giant dropdown is the way to go ? Honestly, I think it's going to annoy more people than it helps. It's not very useful if you're using a keyboard to navigate.

In a previous comment, I illustrated a tidy collapsed menu tree. With this, you always know where you are within the docs structure. And since it's only showing the node's sibling pages, it's pretty short. Did folks not see or it or do they think it's a poor design pattern?

pillarsdotnet’s picture


Perhaps it would be better if you posted a whole-page mockup showing the menu tree in its proper relation to the rest of the page,

JuliaKM’s picture

@lisarex: I started sketching out what the page would look like with a collapsed menu and wound up with lots and lots of menu items at the same level as Facebook-style status. To see what I mean, look at the existing menu for the documentation on the right. It seems like a collapsed menu could only work for a site with fewer navigation items at the same level. But, maybe I'm missing something.

wfx’s picture

It is a lot of menu items to fit on the screen.
This is the kind of menu depth we have to reconcile

Best practices
Building the site functionality
	Access Control
	Actions, Triggers, and Workflow
	Commerce and Advertising
	Connecting to other Sites, Systems, and Data
	Content Authoring Modules
	Content Display Modules
	Content Modules
	Content Recommendation
	Dates and Events
	Documentation tools
	E-Mail and Messaging
	Features packages
	Geographic Information
	Input formats
	Media and Files
	Search Engine Optimization
	Social Networking and Collaboration
		Community building and social networking modules
			Activity Log
			Advanced Forum
			Advanced Profile Kit
			Application Toolbar (Appbar)
			Artesian Forum
			Author Pane
			Buddylist2 Package
			Buddylist: list your social network
			CiviCRM: manage community contacts, relationships, and activities
			CiviNode and CiviNode CCK: Tools For Integrating CiviCRM Contacts Into Drupal 				
			CiviRelate: Dynamic Relationship Creation in CiviCRM
			Comment Notify
			Crew Connect
			Drutalk Installation
			FOAF: friends of a friend
			Facebook Share
			Facebook-style Micropublisher
			Facebook-style Statuses
				Facebook-style Statuses - 2.x branch
				Facebook-style Statuses - 3.x branch
				Facebook-style Statuses: Troubleshooting
				Tips and tricks - 3.x branch
			Family: Record, display, and analyze genealogical data.
			Flag Friend
			Front: Show group membership and events
			Gigya Socialize Module
			Invite: send invitations to join your site
			Notice Feed
			Profile Setup
			Service Links
			Sports Pickem
			Taskbar (communitity builder toolbar)
			Tellafriend Node
			User Relationships
			UserTag:Tag users with taxonomy terms
			meetü: The Social Networking Game from the OPL @ RIT		
		Comparison of social links modules
		Organic Groups
		Voting, rating, and evaluation modules
	User-Generated Content
Contributed modules
Core modules
Site builder's toolkit
Site building: beginner, intermediate, advanced
Site recipes

If we were to make this the Plone style dropdown nav, what would that menu item look like expanded? Would it start at Facebook style statuses and only show from there down or the whole menu tree like above?

With a collapsed menu, would only the immediate child folders shown?

ClosedFacebook style statuses

Facebook-style Statuses
	Facebook-style Statuses - 2.x branch
	Facebook-style Statuses - 3.x branch
	Facebook-style Statuses: Troubleshooting
	Tips and tricks - 3.x branch

Edit: Rewrote my post to hopefully get my point across a little better. I have trouble seeing any menu solution that isn't a little messy. The mockup shown so far has been very clean and perfect, I wonder if it will work that well in production. I know what it will look like in theory based on the Plone website but I think it would help everyone to see it directly applied with a nav block from Drupal Docs. It would be nice if this expanded menu was applied to the design.

dasjo’s picture

i like #94 better than the dropdown

jn2’s picture

I'm partial to the dropdown first posted in #19. Really does save a lot of space and can show an awful lot of information.

jhodgdon’s picture

Status: Needs review » Needs work

Lisa Rex posted above that the drop-down is not keyboard friendly... that is true. I don't know how to open a drop-down with the keyboard (you can select a choice that you know the name of, but I can't seem to make it open).

So maybe we could test that Plone site mentioned above with a screen reader and without a mouse to see how well it works before adopting that idea. Obviously, if there is no way for a non-mouse user or screen-reader user to get the navigation from a drop-down, we need to rethink. Here's the site to test:

jn2’s picture

I tested it with keyboard. You can tab to the dropdown menu, then use the arrow keys to navigate. You don't see the entire menu at once, but you can use it with the keyboard. And it was something like #15 in the tab order, but that could be fixed.

pillarsdotnet’s picture

You generally open a dropdown with a spacebar or right-arrow, depending on the browser. Tagging so the accessibility team can get involved.

Bojhan’s picture

No need to get an accessibility review, from a UX standpoint this has many big issues. We always found select lists a bad pattern for menu selection and even saw so in usability testing (this is basically the same case). Whenever there are many items or nested items it becomes hard to scan. The navigation that we have now is fine - it just takes up a lot of space. Given that navigation is actually more important than all the meta-data, I think that's a worthy trade-off.

jhodgdon’s picture

I'm not sure I agree that the book nav is more or less important than the metadata. Keep in mind that not everyone (by far!) navigates the current docs via the book navigation, and some of the meta-data is pretty important (such as the part about which modules are being documented, and the page status)...

But Bojhan - thanks for your usability insights... Now, how to incorporate them... It sounds like we should go back to the outline navigation, with perhaps some show/hide to make it less huge? And if we're not having a big yellow box on top for "PLEASE EDIT - THIS IS YOURS", then maybe we can move the meta-information back to the top of the post? sigh. Having a 20-foot-high sidebar was never ideal.

Bojhan’s picture

239.57 KB

@jhodgdon I did a quick mockup, moved some stuff around - let me know what you think. This is how we do design though, we try approaches and critique them till we find the right one (often this involves, trowing in and out of ideas).

Also when we try to double the amount of meta information, we are bound to run into some restrictions and need to consider letting other parts be less (we do not really have infinite space).

What did I remove? The long copyright (can we shorten this?). The "please edit" message (we don't have it now, can we a/b test or so if introducing it creates more contribution) - or perhaps append it to the status when its "Needs updating - please edit the page".

Some ideas so far, let me know what you think.

webchick’s picture

The entire point of this though, I think, is to make it clear that people should edit these pages. So I think we need that "PLEASE FOR THE LOVE OF GOD EDIT THIS" somewhere prominent in the new design.

webchick’s picture

In fact, the mock in #105 lacks an edit link altogether, from what I can tell. ;)

heather’s picture

(My comment removed. All good. I'm going to leave this. I think you'll figure it out!)

Bojhan’s picture

Do we want the prominent, please edit this on every page? Or just the incomplete ones?

@heather I really dont think its a good pattern, please look outside of Plone - many many many technical docs use the book navigation we use now (its proved itself to work well, devs are used to it, etc.)

The author info is there, where people would expect it.

pillarsdotnet’s picture

I like Bohjan's mockup very much.

Here's an idea: How about adding a little teaser at the end of the "other contributions from ..." list. So it would look something like:

By jhodgdon. Other contributions from itanglo, catch, swentel, and ... YOU can edit this page, too!.

EDIT: In case it isn't obvious, the "YOU can edit..." text is linked to the node editing form.

Bojhan’s picture

Whoa :) That could be really awesome?

jn2’s picture

What would your mock look like if you used the example in #97? That is not an edge case. Also, I think maybe you didn't read Heather's post closely enough. She's not supporting the Plone style menu. (But she has deleted it, so that's moot at this point.)

I really think some form of dropdown is necessary for the kind of menu depths wfx has so clearly demonstrated that we find on d.o. I don't have a problem with the scrollable dropdown, but I'd +1 Heather's idea of combining the two (#92) before I'd go with Bohjan's #105. (#105 also omits the Discussion and Report this page links.)

What about a mega dropdown, as discussed in @Heather's link? Oops, Heather removed it. Let's at least keep it in the conversation. Here's one link:
And here's the link Heather deleted:

dasjo’s picture


1) make it more clear that docs are community maintained
#110 is great i guess, because it both gives credit to those who contributed and may motivate others to contribute

2) docs navigation as dropdown or tidy collapsed menu tree

here i'd prefer something like the second proposal (tidy collapsed menu tree) as it displays more context information which i find crucial in order to know where i am in documentation right now.

jhodgdon also created this sub-issue #1289090: [meta] Improve search/navigation for d.o community docs

jhodgdon’s picture

Um. How about a scrolling list box (like a multiple-select box) with a "Go" button for navigation? It could have just a few elements in it, and wouldn't drop down.

I would make a mockup but I am no good at those... sorry... not my strength...

dasjo’s picture

what are the disadvantages of the tidy collapsed menu tree?

arianek’s picture

Hi all - I've been lurking and reading all the feedback, etc. Looking at Bojhan's mockup, I have some major issues here. It's more like a polish on what we currently have and is missing some of the most important elements/solutions that these updates are trying to accomplish, namely:

1) Nodereference/link to related Drupal projects that the page is about
2) Making it more obvious that everyone can and should edit/help maintain
3) Providing info about what to do if you need more help (forums/irc/moderator)
4) Giving more credit/prominence to authors
5) EDIT: Also, totally missing the tabs at the top of the page (View/Edit/Revisions/Discuss)

Also...less critical, but still important:

6) It's not clear that the discussions (the discussion block links to) are *about this page*
7) The book nav at the bottom of the page is gone (which I think is fine, but others really wanted to keep)
8) I am concerned that over time the list of users who edited the node will get unruly
9) There's flag for the moderator/spam

Things I like:

- Removing the triple title (I know it's sitewide, but Bojhan has indicated above that it's ok to propose changes to it)
- Keeping the discussions block on the right sidebar

Regarding the menus

I don't think that the expand/collapse menu is an improvement over what we currently have, which is why I haven't really addressed it. I think it takes up just about the same amount of space (which is the main issue), though it does make it easier to pre-browse sections without clicking through. As Jennifer has noted, not everyone navigates with the menus - I'd think the vast majority of users come in from a search anyway.

I still prefer the dropdown, as it conserves the most space. I think it is navigable with keys only - once you tab to it, hit enter, and that should pop open the list. Then when you find the one you want, hit enter again. We might need a "go" button though, if we wanted people to be able to keyboard nav fully?

I understand if it's not the "best" usability though. But I haven't seen any alternatives that are as effective in allowing navigation of such a large and deep hierarchy in a smaller area.

JuliaKM’s picture

139.5 KB
321.17 KB

What about using a navigation like Microsoft's MSDN Navigator? All parent and child pages would be represented in the menu, but not sibling pages. Navigation would still be long for some of the higher-level items, but not as long as now. Here's a new wireframe with this type of navigation, as well as a couple other changes discussed in the thread:
- Spam/inappropriate content flag is at the bottom of the page
- Red background is on the right instead of in the node body

The navigation idea comes from this StackExchange discussion. The OmniGraffle file is attached in a zip file.

I still prefer the original, small menu because it is compact and, as mentioned, most people get to the page from searches. But, I thought it would be interesting to mock up the menu like MSDN Navigator.

Bojhan’s picture

Ok, well I tried :(. Goodluck.

pillarsdotnet’s picture

@#117 --

I believe my suggestion from #110 is still pertinent here, also, though the "Other contributors:" section is not as prominently displayed and thus provides less incentive to click on the "YOU can edit this page, too!" link.

c4rl’s picture

For the record, lisarex and I worked on the particular site with the expand/collapse navigation shown in Comment 32, which borrows heavily from Open Atrium's atrium_book.module and admin.module.

You can see this type of interactivity here in the right column. It's arguably better UX than a big select element or a tree that keeps going and going 9 levels deep as shown in Comment #117.

I don't mean to rock the boat too much, but I'd like to discuss the navigation's purpose rather than technical implementation.

I do strongly agree with Comment 45. We have a book structure that has come together over time from many different authors with aptitudes, modes of thinking, judgements of where their node should go. IMHO, any sort of hierarchal website navigation requires some sort of overarching strategy to be sensible. In a community-contributed content environment, this is unsustainable.

Furthermore, book-style tree navigation implies that there is *always* some sort of hierarchical relationship between the documentation pages, which I don't find *is* always the case. I would also argue that an ineffective, malformed hierarchical navigation is worse than no navigation at all; the former is dangerously authoritative whilst the latter begets users to search and use inline hyperlinks.

There once was a time on the web before good search and tagging existed, where in order to find content there had to exist a hyperlink in a menu. Times have changed. I personally find myself arriving at documentation pages via search (as echoed by others on this thread).

I would be curious to see end-user feedback if we simply removed the navigation altogether. I, for one, wouldn't miss it.

JuliaKM’s picture

338.5 KB

Sorry, left off a few key additions in my hurry to show the alternative navigation. I apologize for adding to the confusion.

@pillarsdotnet: added YOU can edit...
@Bojhan: Moved editor info to the left, added discussion block, and status block. Also removed one menu level from the left.

I think that this includes everyone's changes (minus a decision about the navigation).

Navigation options discussed so far include:
- Plone-style menu
- Mega dropdown (#112)
- Tidy collapsed menu (#117, #120)
- Scrolling list box (#114)
- MSDN-style menu (#117)
- No navigation (#120)


c4rl’s picture

@JuliaKM Comment 120 suggests a sixth option you left out: No navigation. :)

JuliaKM’s picture

@c4rl: How could I have left out the most revolutionary option of all? It's there now.

jhodgdon’s picture

RE #121 - There are a couple of things I really like about this mockup (not discussing the navigation style):

a) The box for meta-data and the area for the navigation on the sidebar are different colors, and the meta-data is boxed, so it's easy for a visual user to notice that they are separate. (Presumably if the page wasn't deprecated or containing security risks, the meta-data box would be yellow?).

b) The "YOU can edit this page too" along with editors right at the top of the page. As it is full-width, it only takes up a line or two, and we have been wanting to both give credit and encourage editing -- I think this accomplishes both with a minimum of distraction from the page content. It also makes the meta-data box smaller to not have contributors on the sidebar. Maybe the "history" could be incorporated into the top though, as in Bojhan's mockup? And we should note that we will only list maybe up to 4 or 5 people who have edited the page (maybe selected by number of revisions they made?).

c) One less level of navigation.

d) The "discussions" link has changed to "Discuss this page", which makes it clear the discussions are specific to the page.

A few things are still missing (from Ariane's list in #116, etc.):

1) We still need a copyright notice, I think.

2) No "if you need help" section directing people to forums or IRC. This is kind of crucial, as currently most of the comments on pages are really support requests.

3) The Discussions block should maybe also get across the "of this page" idea. Maybe change title to "related discussions"?

4) Flag for moderation/spam is missing.

jhodgdon’s picture

Issue summary: View changes

New screenshot link

pillarsdotnet’s picture

About the "YOU can edit" this page link. You missed a subtle but (IMHO) important point.

Move the word "and" from just before the last credited contributor to between the last credited author and the "YOU..." link.

Now it looks like we're pre-emptively crediting the reader with being a contributor. Much more encouraging.

And we should note that we will only list maybe up to 4 or 5 people who have edited the page (maybe selected by number of revisions they made?).

We should list the most recent 4 or 5. That way, someone who contributes (even in a small way) gets the instant gratification of seeing their username listed on the page.

The main goal of this issue is to encourage contribution to community docs, is it not?

arianek’s picture

I think this is definitely getting closer (assuming jhodgdon's comment 124 is incorporated)... or at least, we're all mostly on the same page about things other than the menu!

For menus, I don't really think *no* menu is an option - it would make it impossible to browse the site, which is a bad thing. But... regarding the expand/collapse menus like OA and the mock lisarex posted - in theory I like the idea and look, but my problem with those has always been that when you use the OA style ones that allow you to pre-browse before clicking on a particular page, it can become confusing or easy to lose your spot in the menu. I haven't found them particularly "usable" despite being a bit more space efficient.

There's got to be a better solution to the whole menu question... but the real question is should we figure it out before signing off on the rest of this plan?

jhodgdon’s picture

A few more ideas/thoughts on the latest mockup:

1) Block title for top of right sidebar -- something other than "Status"... wasn't it "About this page" before? The problem I see with "status" is that it contains the page status, the projects referenced, the audience, etc. Not just status.

2) Can we add another Edit link at top of right sidebar? That would hopefully make it clearer how to edit the meta info (which is always a conceptual stumbling block for new contributors).

3) I like pillarsdotnet's suggestion of "most recent 4" for the author list.

arianek’s picture

NOTE: Please continue discussions about the menu at: #1289090: [meta] Improve search/navigation for d.o community docs, we're going to focus on non-menu stuff here and work on the other issue concurrently.

JuliaKM’s picture

672.78 KB

Here's an updated version.

1) The right block title is restored to "About this page" and includes an edit link.
2) The current navigation is back! Not because it's got an advocate but instead because the navigation discussion has moved to #1289090: [meta] Improve search/navigation for d.o community docs.
3) pillarsdotnet's wording is incorporated.
4) The copyright notice is back.
5) I added a yellow box is back at the bottom of the page leading people to IRC and the forums. I figured that this was where people would look to comment first.

@jhodgdon: the spam flag has been hiding out all along at to the right of "Add new discussion." Should it go somewhere else?

jhodgdon’s picture

Thanks Julia, looks great!

Wow, this actual example makes it so clear how huge and crazy the current nav is (oh yeah, don't discuss this here).

Anyway. A few other thoughts/minor tweaks on this:

a) Contributors line - how about:
Originally by maryb. Edited by jimq, johnd, janef, ... and YOU can edit this page too!
Created: Jan 10, 2009. Last updated: Jun 12, 2011.

(Then we can remove the date created/updated from the sidebar too.)

b) Page status - currently it just says "Deprectated". I think it needs a label:
Status: Deprecated

c) Is there room for the Edit link to go right of the About this Page header in the block (on the same line)?

d) Maybe put the whole line of "add child page, report this, etc." into the yellow box at the bottom? I still had to search to find that "report this as spam" link.

webchick’s picture

Other than the pink background on "About this page" (pink already has connotations of "unpublished" or "broken"), this looks really good. I'd leave that just white and call it RTBC. :)

webchick’s picture

Issue summary: View changes

Add list from #121, and also add markup.

pillarsdotnet’s picture

a) Contributors line - how about:
Originally by maryb. Edited by jimq, johnd, janef, ... and YOU can edit this page too!

How about this (very small) tweak?

By maryb, ..., jimq, johnd, janef, and ... YOU can edit this page too!
   1      2          3             4    5              6

The objective is to communicate (in a very compact way) the following as someone reads the line.

  1. "maryb" was the first contributor.
  2. The comma and ellipsis indicates an unknown sequence of additional contributors.
  3. The most recent three (or four or five or however-many) contributors are listed.
  4. A trailing "and" indicates the last item in the series. (who will it be?)
  5. Another ellipsis to briefly pause for effect.
  6. Surprise! You can be part of this list, too!

Also, updated issue summary, moving the navigation menu choices to the sub-issue created to discuss them.

arianek’s picture

Status: Needs work » Needs review
137.04 KB

Alright I think I've got most of the input incorporated, and tweaked a few things along the way...


- Pages with a bad status will still have the little caution icon (that is currently used).
- We'll sort the menu out separately.
- Once we sort the menu out, we might add the Discussions block into the sidebar if there's space.

Can we get an RTBC so the dev plan can be given a final review + breakdown?

EDIT: ps. I left out the additional "edit" link in the metadata block because it looked a bit cluttered, and I thought it was sort of redundant/obvious.

arianek’s picture

207.97 KB

ps. graffle file updated...

rfay’s picture

I think it's excellent. I just love the meta-information about authors, editors, and dates. And the 'discuss this'. But IMO all "discuss this" or comments (if that's equivalent) need email notification for sure.

arianek’s picture

Just filed #1299822: Update Docs Management view to add the new Project reference and Keyword fields to the Docs mgmt view as well, since that will become a lot more useful then for project maintainers or people helping keep the community docs up to date.

JuliaKM’s picture

#133 looks great to me. Thanks arianek!

I still like the idea of turning the side block red when a page is depreciated or has insecure code, but I think I might be in the minority. I just don't find the caution icons particularly eye-catching and sometimes notice the icon after reading through an old page.

That being said, if everyone else is good with #133, thumbs up. Can this be marked as RTBC? Afraid to push the button...

pillarsdotnet’s picture

Can't be RTBC until the navigation menu is sorted, but I'm fine with #133 as well.

arianek’s picture

Re: #138. There's no reason to hold this RTBC up on the menu, we can work on that independently of this issue.

I'm not going to RTBC it since I did the last mockup - whoever supports next, pls do!

pillarsdotnet’s picture

I don't understand. We're going to roll out code that has a big "X" where the navigation menu used to be?

Where's the sandbox link so I can see this in action?

arianek’s picture

@pillarsdotnet It's a mockup. The X represents the existing menu which is not going to be changed in this issue's work. It was used to save space (and I thought was quite obvious as it maintained the menu's title and placement).

EDIT: and there's no sandbox yet - this is just in the planning phase, not the building phase. We are trying to gain consensus on the plans.

pillarsdotnet’s picture

Okay, then Remaining tasks should include something like "We have agreed upon a redesign; now it needs to be deployed to a sandbox for testing."

Now that I look at it, the whole Remaining tasks section looks confusing to me.

Could someone please surround the already-completed tasks with <del>...</del> tags so we can tell what's done and not done? I don't see how something can possibly be "RTBC" while there are 12 remaining tasks (some with sub-tasks) that have not been completed. How can something be "Reviewed and Tested By the Community" when it does not exist except as a generally-agreed-upon idea?

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

I am going to update the issue summary now.

Also marking RTBC. :)

jhodgdon’s picture

Issue summary: View changes

Note that discussion of the navigation menu has been moved to another issue.

jhodgdon’s picture

Issue summary: View changes

Update with current plans, new issues, etc.

jhodgdon’s picture

Issue summary has been updated and some new issues are filed and/or updated.

jhodgdon’s picture

Issue summary: View changes

add flag issue to the summary

webchick’s picture

So, what's the next step here? Do you need me to spin up a d.o development sandbox and give a bunch of people access? (I'm not sure how to do that, but I'm sure I can figure it out :)). Do we close this issue and instead re-open a bunch of sub-issues to implement chunks of the mockup?

webchick’s picture

Also, checked in with both killes and drumm. Their feeling is since this is the docs team's section, you have pretty free reign to do what you want, as long as it doesn't bar from upgrading to D7 (sticking with good quality contribs should help with that), and it doesn't incur a performance penalty (we'll need before/after EXPLAINs for any new queries/views before deployment).

webchick’s picture

Issue summary: View changes

add link to curated docs issue

jhodgdon’s picture

We have a few issues in progress now, and I just updated the issue summary above to highlight some issues that we need either input on or for someone to take on. Some of them may just need an admin on d.o directly (like creating taxonomies and flags - I don't think we do that in modules but not sure?).

I think the next step is to get those issues taken care of (the site building ones), and then we can try deploying on a sandbox. But until someone has built the forum noderefs and the project noderefs, there doesn't seem to be much point in trying to put it all together?

pillarsdotnet’s picture

Title: Make it more clear that the current Documentation on is community maintained » Develop a plan to make it more clear that the current Documentation on is community maintained.

After fixing the issue title, now I see how this can be RTBC.

webchick’s picture

Hm. Well then what if we marked this issue "fixed" and moved the issue summary above to a meta issue to implement the plan? It's a bit intimidating to point volunteers at a ~150-reply issue with lots of heated debate and say "GO NUTS." :) And I worry that leaving this open will mean the debate about what the plan should be will remain open.

jhodgdon’s picture

OK. I'll take care of it later unless someone beats me to it. Kind of busy at the moment...

jhodgdon’s picture

However if we do that we need to go to all the referenced issues and fix them to point to the new issue too, so it's not a 2-minute task.

yoroy’s picture

Status: Reviewed & tested by the community » Needs review
262.8 KB
253.06 KB

I’m very glad to see some discussions moved to their own issues. And the design has drastically improved because of it. Good work. But I think this needs a bit more detailed design before rtbc-ing. I have less than 10 points I’d like to discuss a bit more in depth :)

These comments are based on the latest mockup in #133

mockup of a docs page with redesigned meta-info block and new links for editing and discussing the page


A ‘Discuss this page’ link with a comment-balloon icon to the right of it is added to the row of View, Edit, Revisions tabs. I wonder:
- Doesn’t this come to soon? How can I know before-hand that I want to discuss this? Said differently: the trigger of wanting to discuss this might well be more effective when offered after the actual page contents. Since this sort of replaces the ‘Add comment’ link (I think?), why not keep it at that position?
- Realize that by adding another link to the row that contains the primary ‘Edit’ link effectively detracts attention from that ‘Edit’ link. The more competing options, the less attention for each individual item. We can’t tell if that will be remedied by more constructive discussions because of the ‘Discuss’ link, but it is a trade-off and it should be made consciously. I think the ‘discuss’ link comes too soon here and thus am afraid that it will not be effective here. Thoughts?


I wonder if the ordering of there is prioritized correctly. It’s not only about attracting more people to start editing. The last modified date, compared to a first publish date are important indicators of page relevance/accuracy, which is useful data for anybody visiting this page.

The current proposal lists 6 persons: authour, 4 last editors and ‘you’. I think this may be overdoing it and I would suggest to list just only the latest editor. Listing too many may just as well give the impression that this page is well off with all those nice people taking care of it, so why should I bother? Triggering to contribute in context of ‘seeing your name here’ plays into ego. While I think it’s perfectly fine to see your name show up after you’ve edited it, I don’t think it’s the right place to do the actual call to action, it seems to me to play too much on the vanity card. Would rather see the call to action put in context of page status (see 4) and the discuss/report link (see 8)


All caps ‘YOU’ and exclamation mark, that’s plain shouting no? I don’t think the need for more community editors should seep through in an almost desperate tone of voice here. Shouting never helps your argument.


The page state of ‘No known problems’ is an excellent place to trigger for edits. In comment #127 jhodgon suggests adding an ‘edit this page’ link especially in this block, based on her observations of how new contributors interpret things. I think it was too easily dismissed as redundant/obvious. Right at this status message you will trigger people who either disagree (“oh, yes, this page has problems”) or can otherwise help improve things.

Also, how will this work when somebody has started a discussion on this page? Will the next person start another discussion or be linked to the existing discussion?

Using color to emphasize page status is fine, but don’t apply it to the whole block (which suggests all the info in there wrong) but only to the status itself.


‘Content info’ is a relatively meaningless label no? Mostly redundant with the ‘About this page’ block title.


Related projects info is awesome. So much so that I think it can be set apart from the other info above it. I assume this can become a small to medium-sized list of items, which would be better of with a list of projects each on their own line instead of a running listing.


Why the yellow background here? The yellow is now used to visually label the meta info. I don’t think it is wise to repurpose the same color for a different set of links.


In the row of links of ‘Add child page, printer friendly’ a ‘Report to moderators is added with an added little flag icon. Currently, the ‘add new comment’ link is here.

Before having to further specifiy the behaviour of this feedback workflow in its own issue, I have some more strategic considerations:

Why fork the roads for providing feedback by provinding 2 different paths for giving feedback (‘discuss this page’ and ‘report to moderators’)? How is this different from the ‘Discuss this page’ link? Could this ‘report to moderators’ flagging be made part of (postponed within) the process of ‘Discuss this page’?

I’m a fan of removing the ability to directly comment for all the obvious reasons. But, the people that do comment are for a big part the exact people you want to convert into directly editing it. So, I’m not sure if this is the best replacement link for ‘Add new comment’. Drupal has a very baked-in pattern of where the ‘add new comment’ link goes. Wouldn’t the ‘Discuss this page’ link be better off here? I’d rather ‘hijack’ that default expectancy towards the discussion, not towards reporting to moderators.

Something to be aware of with ‘report to moderators’ feature: it seems to introduce a bottle-neck for maintenance: how big is the team that will see this moderation queue, what can they do there? (yup, different issue, but the interplay with ‘discuss this page’ functionality is in scope here I think).


Try to avoid using ‘Please’. The intention is politeness but it’s easily percieved as patronizing. Suggested rewrite: “Looking for support? Visit the forums, or join #drupal-support in IRC.” Or just drop the ‘please’ from the proposed sentence, that’s ok too. Minor niggle in the scheme of things :)


This is an reworked wireframe trying to incorporate the above:

wfx’s picture

The Community & Support page has an awesome "Search Documentation" bar in the sidebar which updates your results as you type. Guess I'm not sure why this was never added to the Docs pages too. I know it's a duplication of effort since it is on the other page but it's still useful. Perhaps it's a space issue, it does need a lot of real-estate in the sidebar to display those results.

Sorry if this has already been discussed, I've seen references to improving search and faceted search but not about adding this search bar to the Docs pages.

drumm’s picture

That was originally designed as the "How can we help you?" box at I didn't think we could come up with something smart enough to answer that, and documentation was already in the search index. It does the same thing as search documentation in the big search box, but with 200% more AJAX.

wfx’s picture

Everything is better with 200% more AJAX :)

Other thoughts - Okay, with that being the original purpose I can see why it was left off Docs.

arianek’s picture

@yoroy thanks for posting a new mock up of your ideas (though it's going to make it tough to do further updates on now that it's in a png format...)

most of the changes seem sensible, some i'm ambivalent about ;) ...but the ones about the discussion/moderation links are problematic, so i'll stick to feedback on those.

we don't want a link that says anything like "suggest improvements". that implies that you're suggesting it *to* someone, which is not the case. the whole point of this is to make a more blatant shift of power + responsibility to the community for maintaining the docs. that's why we used the discussion + flag approach (to replace the commenting + issue queue).

for the "discussions" (which are noderef'd forum threads), i used the comment icon to make it visually consistent so users instantly realize that's where they should go to when comments are gone. your rationale about the location of the link makes sense but i really think it's important that it say "discuss this page". namely i thought since the comment form will be gone, it'd be better for the link just to be bigger (which is why i moved it to the top).

the flag to moderator is only for spam/inappropriate content. it's not about monitoring the actual content otherwise - that should be done *by* the community in the discussions and by editing the page. so hopefully we won't have too much flagged content - and it will be monitored by docs admins via the docs management view.

does that make sense? and if so, do you have suggestions to fine tune accordingly?

yoroy’s picture

219.36 KB

Ah forgot to attach the graffle. Yay dropbox.

Thanks arianek for feedback on exactly the bits that needed it most. Agreed on the need for wording the discussion link as you proposed. I can't respond too in-depth right now, but for an updated mockup I would look into:

- Rethink if a 'discuss this page' in the page status still makes sense: maybe the 'report' link is more fitting:
- Make the 'report to mods' link a part of the page status block (without making it too prominent, but the page being flagged is a useful status indicator I think, so seems to make sense to group that information and actions around that.
- Keeping the 'discuss this page' at the bottom (it could keep the icon then). Goal is to promote 'Edit directly' first, discuss second, right?

I'm still not clear on what 'Noderef'd forum threads' look like. Can we expect a list of links to forum threads? Will I be able to start a new discussion or am I supposed to add to an existing one? There are multiple states to the ui of this functionality that need spelling out but seems that's what #1027608: Use forum to make Discussion tab/block for Book pages is for.


jn2’s picture

I much prefer the 'Report this page' and 'Discuss this page' as they are in the (previously) RTBC #133. I also prefer the yellow box at the bottom.

jhodgdon’s picture

Thanks yoroy for your ideas...

Regarding your suggested changes in #152, in order:

1. As Ariane said, we want it to say "Discuss this page", not "suggest improvements". We definitely want people to just edit as a way of improving the page, not make suggestions. I'm OK with moving the discuss link somewhere else to make it less prominent than edit though.

2/3. As discussed extensively above, we're trying to get people to feel comfortable editing, and we're trying to give more credit to contributors. Your modification takes away both of those benefits from this area. So I prefer #133 in this area. We can remove the all-caps on YOU though.

4. Of course, I agree with this - I don't think it's obvious to everyone (based on past experience) that the way to update status and other meta-data is to click the main "Edit" button. But I don't like the suggested change in #152 either -- the edit/discuss block does not belong as part of "About" IMO, and you lost the Page Status entirely. My suggestion would be to put a small "Edit" link on the same line as the "About" header, if we can fit it in.

5/6: I prefer your formatting of the sidebar meta-info (still needs to have Page Status included as well).

7: I really like the yellow box, because it makes it clear those are different from the main page (i.e., they are actions and not content). I'm open to a different color or formatting that also makes that clear. The current yellow color for meta-data is kind of silly IMO though, so we shouldn't be comparing the new yellow box to the previous yellow box, just asking if the new yellow box makes sense. :)

8: The "report" link is a flag (which I assume will be on/off by node and not per-user). It is not the same as a discussion at all, and is meant to be used for spam and inappropriate content only. We definitely need this -- it will let moderators find and check out pages that need immediate attention (we have a doc management view where you can find such pages). Maybe we can make that difference clearer, but "suggest improvements" is not the right answer (as Ariane noted above), and they won't be combined (discuss is a forum post, and this is a flag).

9: You are quite right about "please". Whoops! That has been brought up before on previous issues and we all forgot. :)

So... someone who can make mockups, want to do another try? Please? :)

arianek’s picture

@yoroy re: "I'm still not clear on what 'Noderef'd forum threads' look like. Can we expect a list of links to forum threads? Will I be able to start a new discussion or am I supposed to add to an existing one?" Yes you will have a list of links either on the book page or a forum container page. Yes, you will be able to start new discussions.

@all - before i try and mock up the changes (getting tight on time with family visiting all week and then the PNW Drupal Summit!), I want to note that the idea with the discussion tab at the top is to be more "wiki" style and was in the redesign mockup which didn't end up being implemented, just for an idea of what was intended. i still think this would be good to make it more visible if the list of discussion threads won't be in the sidebar of the actual book page.


webchick’s picture

To me that just looks like regular comments + Would certainly be a lot less work than trying to node reference forums and keeping both forums + book as close to core as possible helps ease the upgrade path.

arianek’s picture

OH. EM. GEE. how did i not know about this module?? ok, let me sleep on this, but it seems really good on first glance!!!

pillarsdotnet’s picture

A great big +1 on moving Docs page comments to a separate tab.

MGParisi’s picture

+1 to 162, Talk is amazing. But I would like the TALK page to be a wiki page! Or we allow allot more people to edit/delete comments.

MGParisi’s picture

+1 to 162, Talk is amazing. But I would like the TALK page to be a wiki page! Or we allow allot more people to edit/delete comments.

jn2’s picture

@arianek #160

A big +1 to keeping the 'Discuss this page' link at the top, just as you had it in #133. Moving the comments and eliminating the issue queue are big changes, and people need to see prominently what is now available.

silverwing’s picture

arianek’s picture

@164 pillarsdotnet that was part of the original proposal/plan from last december, not a new idea - it's just the implementation we're looking at differently - using talk module might be better and easier to maintain than nodereferencing forum threads.

@165 mgparisi - that's not completely possible because we don't want comments deleted easily, but the plan is to increase the number of admins who can manage comments.

@167 jn2 - yah, the more i look at it, the more i feel like it's a pretty important piece.

@168 silverwing - i think that would be a great feature to add, though probably in the second round of improvements - be sure to add a link on #1287784: Follow-ups to improve the community docs k?

yoroy’s picture

Responding to #159 and Arianek:

1. I'm sold on having the 'Discussion' link up there as a tab, following the idea of Talk module, this makes much sense I think. Suggest 'Discussion' because for tabs we prefer noun-y labels (and use verbs for action links and buttons). I hope it will end up there without an accompanying icon. Does Talk module add the tab and leave the comments link below a post or replace the add comments link?

2/3. It's ok to name a couple of more names. Just keep the relative importance in mind. I still think modified/created dates should be leading with naming names second. I'll keep it at that and let you decide what goes here exactly.

4, 5, 6: see updated wireframe for my ideas on the status info box. I still think status info + edit/discuss links as a combo is a more potent trigger than the names of those who edited before. I'm not sure what kinds of statusses there will be so these are just suggestions.

7. For the 'support?' message at the bottom, again, consider the relative importance of this bit of info. How necessary is it to visually differentiate this sentence to get the message across?

## Mockup:


arianek’s picture

@yoroy You know what? I'm gonna have to whole-hog +1 #170! I like all the updates! Thanks for helping out with the UX finesse.

As for the page status, the current statuses will be carried through, which are the following (with my color suggestions below - related to technical side's appropriate level of warning):

- No known problems (green)
- Incomplete (yellow)
- Insecure code (red)
- Needs copy/style review (green)
- Needs dividing (green)
- Needs technical review (yellow)
- Needs updating (yellow)
- Deprecated (red)

dasjo’s picture

#170 look very clean

just an idea for the page statuses, maybe we could have a "mark as ... " action which lists the different statuses as a dropdown? this idea just came to me as for comments we are planning to have #34496: [meta] Add Flag module to allow users to subscribe/unsubscribe without posting a comment while in this case one would be able to mark the documentation page as "incomplete" for example and input a reason as revision information for example

arianek’s picture

@dasjo - unless i'm missing something, that's how it already works. this isn't a new field, it's a dropdown on the book pages.

dasjo’s picture

@arianek - yep, i was just thinking about providing a "flag as ..." functionality directly on the documentation page without the need to click edit and look for the dropdown :)

jhodgdon’s picture

RE #172/#174 - the page status is a taxonomy, and it has a bunch of choices (listed in #171). Flag only allows you to have a binary choice (flagged or not flagged), so I don't really think we can switch the page status to be a flag. Meaning also that if you want to change the status, you will still need to edit the page to update that taxonomy value.

Which is why there is an Edit link just below the page status now in the sidebar (hooray!).

Big +1 on #170, with the colors posted in #171. The only thing I'm not sure about is whether the "Page Status" heading in the right sidebar actually represents all of the information that is there -- I think it only applies to the first line, and the rest is actually "about this page" or "meta" information, not really "status"?

jn2’s picture

I'm confused. Was there a decision made not to include the 'Report to moderators' flag? In #159 (#8) it was still there and important, and that's the last mention of it I see. Or am I blind and not seeing it in #170?

jhodgdon’s picture

#176 - Good point, that got lost in #170. I didn't see a decision to remove that either, and yes I think we all agreed it is important.

arianek’s picture

Ah I missed the missing moderators link - yep, that'll need to be added!

jhodgdon’s picture

Actually... Here's one thing that we haven't thought through yet, in 178 comments.

The moderation link is a flag, presumably a global (per-node) flag and not a per-user flag.

Meaning that it's actually kind of a "page status" -- as in "This page has been flagged for moderation" is a status of the page -- it's useful status information for people to know.

So maybe this should go up in the right sidebar in a line just under the page status taxonomy? If the page has not been flagged, it would have a link (if you are logged in) saying:
Report to moderators
And if it has already been flagged, it would have a red box saying:
Page has been reported to moderators
(or some better text hopefully someone can think up that will communicate this clearly and concisely). And when you hover over this text and have permission, it would change to a link saying:
Un-report this page
(again maybe someone can come up with better text -- the creative part of my brain is not quite awake yet). Note that we already have similar changing flag link/text stuff going on with the new (and extremely wonderful) flag implementation for following issues, so it must be feasible.

I also think that ideally only moderators should have permission to unflag a page... although I just checked, and at least in the Flag 6.x-1.3 module (the current full release -- there's also a 6.x-2.x-beta release that I haven't tried - not sure which version we're using on d.o?), there does not seem to be a separate permission to flag vs. unflag a global node flag. And I'm not sure we even want to limit unflag to moderators... thoughts?

arianek’s picture

761.44 KB

Incorporating Jennifer's feedback from #179 about the report to moderator link... maybe yoroy (or someone designy) can advise if this is awful. ;)

- 8 "Report to moderator"
- 9 "Page has been reported"
- 10 "Un-report this page"

jhodgdon’s picture

I'm still not entirely convinced that the "page status" headline on the right sidebar is the right heading, but other than that I'm +1 on #180. And I'm willing to go with "page status". :)

jn2’s picture

What if that area didn't have a headline, and 'Page status' were formatted like the other labels, just bold with a colon and right above the actual status? It's pretty obvious that the information is meta information, so a headline may not be necessary.

arianek’s picture

740.46 KB

Ok, once more after Jennifer and I tweaked the block titles...

jn2’s picture

+1 Looks good!

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Dare I? :)

Let's build it!

I'll update the issue summary soon...

jhodgdon’s picture

Issue summary: View changes

Update status of the tasks

jhodgdon’s picture

Issue summary is updated.

jhodgdon’s picture

Issue summary: View changes

Update to new plan

arianek’s picture

Thanks Jennifer!

jhodgdon’s picture

Slight update to the plan. 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. I'll update the issue summary here (and a couple of related issues) accordingly.

jhodgdon’s picture

Issue summary: View changes

Update status on two issues

jhodgdon’s picture

Issue summary: View changes

Update plan for issue report for moderation vs. flag

jhodgdon’s picture

Summary and related issues are now updated! The next task is the redesign of the community docs pages. We need someone to take that on... "Someone" could be me, but if someone else wants to do it, please speak up!

jhodgdon’s picture

First pass at the redesign is available for review -- see

jhodgdon’s picture

Issue summary: View changes

one more small tweak about not using flag any more

jhodgdon’s picture

Issue summary: View changes

update status of tasks

jhodgdon’s picture

I just added a small bit to the task list in the issue summary - a note that we need to edit the Help Us Maintain sidebar of too.

drumm’s picture

Second pass is available for review

drumm’s picture

There are a couple bugs with the section navigation, and a change to how we do navigation on subsites like API. This means the section title and navigation, or lack of it, needs some thought at #1392196: Redo Documentation section navigation. There should be something letting people know they are in the community documentation section of the site.

jhodgdon’s picture

The main goals with this design:
a) Don't use up extra space on every page with two rows of headers/tabs. We didn't think it was necessary to say "Documentation" as the section header, then "Community Documentation" below that in a tab.
b) Make sure it says "Community Documentation" prominently at the top, not just "Documentation".

I don't think we care whether the "Community Documentation" text is a tab or some large text, as long as it says "Community Documentation" and it's at the top. And if we have to have a section header saying Documentation still, for consistency with the rest of the d.o site, that's OK (though it seems to waste space).

I'll put that on the other issue too.

jhodgdon’s picture

Oh and we probably don't need the Recently Updated tab necessarily either... maybe just get rid of the tabs and make the section header say Community Documentation?

jhodgdon’s picture

The first pass on this has been deployed!!!!!!

jhodgdon’s picture

Issue summary: View changes

Add bit about editing the sidebar on docs landing page

jhodgdon’s picture

Issue summary: View changes

update status of in-progress issues

jhodgdon’s picture

The issue summary above has been updated with current status... We still have some follow-up to do.

I just filed this follow-up issue, which we need to resolve soon:
#1401960: Edit the Documentation landing page sidebar block
And this lingering issue also needs to be resolved:
#1275424: Deal with documentation role and documentation input format
(actually that one involves unlocking a bunch of pages and getting rid of that role)

By the way, I already edited the pages over the past few days to reflect the new Community Documentation philosophy, and I also edited the text at the top of the Documentation create an issue page:

webchick’s picture

Woohoo! Great work, everyone!! :) Thanks for the assist, Neil.

arianek’s picture

Yay! So should we close this and follow up on the other bits on the separate issues then?

arianek’s picture

Issue summary: View changes

more updates

jhodgdon’s picture

Status: Reviewed & tested by the community » Fixed

Actually, yes -- I'm marking this "fixed".

I just filed
#1402848: Put documentation comments in a separate tab
for the Talk module idea, and added that to this issue summary. So all the follow-ups in the "remaining tasks" section in the summary are now separate issues tagged with "docs infrastructure", except the "recruit moderator team" and "issue queue cleanup sprint" items, which I will need to organize (I've added that to my To Do list).

I'll edit the issue summary one last time to ask for NO MORE COMMENTS here (follow up on the other issues).


jhodgdon’s picture

Issue summary: View changes

Add issue for Talk module idea

arianek’s picture

Yay! But I have one more comment, more of an anecdote...

Within a couple hours of this roll out yesterday, I had this conversation:

Other person: "Hey Ariane, can I ask you something...?"
Me: "Sure..."
Other person: "Look at this, did something change on the documentation? All of a sudden I can edit pages, there's an edit link on the side..."
Me: "*Laughing* yes something did change, but you were always able to edit the pages, we just made it more clear!"
Other person: "Crazy, so I can just... *clicks Edit link in sidebar*...wowwwww..."

And with that, I felt our work was a success. Apparently the edit tab was invisible even to seasoned D.o users - but the link on the side was instantly noticed by someone who didn't even know for sure something had happened.

Good work y'all.

jhodgdon’s picture

YIPPPPPEEEEEEE! I like having at least one data point that this effort was a success. Thanks for sharing that, made my day. :)

yoroy’s picture

That's awesome. Props to all involved for having a real design process in here.

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

Anonymous’s picture

Issue summary: View changes

Edit to make clear this issue is closed, and where to follow up.

jhodgdon’s picture

Issue summary: View changes

update - link to issue cleanup sprint