Proposal for Block related to Contributors to Show on Doc Pages

Where in the current set of blocks do you think this block should be placed?
Left or right side?
Top or bottom of the column?
User able to enable or disable it?

I maybe wasn't clear enough: I don't want to enable the revisions tab for anon users. It does not offer any helpful additional information.

Background: I've recently disabled all urls which have "sort=" in them. This resulted in 750k of URLs being blocked for google now. There are however robots which won't honour this request and I don't want to add more publically visible URLs.

I like this idea a lot. One suggestion: "Learn how you can contribute documentation too!" should probably be linked to http://drupal.org/contribute/documentation. There's a lot on the /contribute page, and documentation is only a small piece of it. If we want to steer people to /contribute, different link text might be in order.

The revision bit will be edited out. I am more interested in the visible ad for help part.

I hope we can get the revisions tab enabled. But if we can't, at least make the message say, "To see contributors to this page, log in and click on the "Revisions" tab. You can be a contributor, too! To find out how...blah blah"

What about something like this for the revised text?

<a href="/node/14205">Hundreds of people</a> have contributed to Drupal's documentation, and you can too! New users of Drupal have a fresh perspective on what other new users need and are especially invited to participate. <a href="/contribute/documentation">Learn how</a>.

Note that:

• The link to http://drupal.org/node/14205 was suggested somewhere along the way in the mailing list discussion and may be useful since it seems there's no acceptable way to link to the current page's contributors...
• I tried to shorten the text a bit, in anticipation that it might go in the sidebar, which is kind of narrow. But I think the original longer text is good too, and I worry I may have taken too much out.

Also, a minor point: Shouldn't the title of the block be "Thanks to Our Documentation Contributors"?

As for the block placement, I agree that the left side above the handbook license makes the most sense logically. However, just an observation: The book navigation block has a tendency to get extremely long (especially when you are several levels deep in the documentation hierarchy), and on those pages any blocks below it pretty much get lost from view.

I don't think I have any brilliant alternative suggestions, though.

As requested, copying from the other issue...

Copy of http://drupal.org/node/263490#comment-860952 :

I like #6, which is along the lines of my suggestion on the email thread. I'd then modify the block listed in the other issue to say:

The following people contributed to this page of documentation: [ comma delimited list of unlinked names here ]
Learn how you can contribute documentation too! New users to Drupal are especially invited to create documentation pages. New users have the freshest perspective on what other new users might need. Documenting the hurdles you have overcome is invaluable for future new users.

It's simple, gives credit without worrying about how "much" credit each person deserves, has no links which makes it harder for emailing questions, and makes it clear that anyone can join that list and help out rather than it being a single person owning the page. And it respects the "won't fix" on this issue.

#6 refers to http://drupal.org/node/263490#comment-860179 copied here:
I'd really prefer a block that lists the contributors

select distinct(u.uid), u.name from node_revisions n inner join users u on u.uid = n.uid where n.nid = %d

A list of contributors in the block was part of the original proposal I posted on the documentation list: http://lists.drupal.org/pipermail/documentation/2008-May/006023.html So I'm down with that.

I always envisioned in on the right hand side of the page, below the user login for anonymous users and below the contributors links for logged in users.

I'm reposting this over from http://drupal.org/node/263869 - had no idea this issue existed and it was inappropriate for that one. This was written before I saw any of this, but it's along the same lines:

IMO there's at least two issues it needs to address:

1. People looking at a handbook page can't see way to edit it (or add an extra page if they're not logged in).

Information about joining the docs team is displayed prominently in the handbook tree as sepeck pointed out on that thread, but in my experience on other sites with a reasonable amount of content, most traffic to these pages will not be via this tree - it'll be in and out of multiple related pages via core search or google - rarely down from the main navigation, and rarely upwards back to the main navigation.

2. Some people want more obvious credits for contributors to documentation. Some (like me), don't want their name plastered over handbook pages they may have changed a typo on and forgotten about a minute later.

Very, very rough outline of what might be in the block - would need to be shown depending on user permissions:

'Register or log in to comment on this page, see revision history or create a new handbook page.' - so similar text, but not in $links

'Join the documentation team to edit this page'.

'View contributors to this page'. - linking to something like node/nid/contributors (update: I'd also be fine with a list of non-linked usernames on the block, although I think this should go at the bottom, under the call for help)

Block would be enabled by default, but optional in user profile. Right column, weighted just above the contributor blocks.

@catch - Why have anything mentioning revisions? If you have an account on drupal.org you can see them. Done.

Why not just focus on a message of contributing and how to do so? Just have the Add a child page and Join the doc team messages.

I like @catch's ideas a lot, with the only caveat being that this block might be getting a bit long. Anyway, in an attempt to merge some of the ideas above, how about this?

Thanks to Our Documentation Contributors!

Hundreds of people have contributed to Drupal's documentation, including many who are new. New users of Drupal have a fresh perspective on what other new users need and are especially encouraged to contribute. You can:

• Login or register to suggest changes to this page, see its revision history, or create a new page [maybe shorten this in response to @sepeck's comment in #14]
• Join the documentation team to edit this page
• Learn more about how to contribute

This is for anonymous users; as @catch suggested, the block would need to have some appropriate permission checks. Also note that some of these links currently appear in the "Quick links" block on the left side of the screen, but leaving that block for navigation-related links and this new one for contribution-related links might make sense. I like @catch's suggestion for the block placement, too.

As for the idea in #10 (replacing the first part with an unlinked list of contributors), I see two potential problems:

1. It would look OK for authors who use their full names, but that's not too common and you could easily wind up with something like this (pulling a couple usernames from the above discussion):
   

   The following people contributed to this page of documentation: Michelle, sepeck, ksenzee,

   killes@www.drop.org

   .

   Some immediate questions this raises are: Michelle who? What's a "sepeck" and a "ksenzee"? Is that last one an email address? And so on ;) I think unlinked usernames could be very confusing for new people to see.

2. What about pages where only one person has contributed? If there is only one name on that list then I think it raises some of the issues that @sepeck mentioned elsewhere, where it might look like that person "owns" the page and discourages other people from contributing to it.

Perhaps these concerns could be addressed via appropriate wording, however.

sepeck: I'm not at all fussed about revisions personally, that was in context with the link text changes from the other issue.

@shai that looks pretty good. I don't think usernames are a problem - wikipedia has them, myspace has them, all forums have them, if you don't know what they are, then you're going to be confused by any community site on the internet.

I'm not sure about "Thanks to Our Documentation Contributors!" - if I saw that on a random site I was browsing, I'd probably 1. switch off 2. think they were about to ask me for money. I'd rather see "contribute to documentation" or "improve this page" or something.

@shai that looks pretty good. I don't think usernames are a problem - wikipedia has them, myspace has them, all forums have them, if you don't know what they are, then you're going to be confused by any community site on the internet.

I think you actually meant to address this to me... anyway, I wasn't saying usernames are bad, just unlinked usernames. Without a link, I think it's hard for people to realize that what they're looking at is actually supposed to be a username, that's all.

I personally don't understand why having the names linked is a major problem, but I guess a lot of people don't want that. The problem I'd be more worried about is that if you only contributed a small amount to a page, and the rest of the page (that you didn't write) is really bad, you still get public "credit" for it, which hurts your reputation in some ways. That's hard to fix without the revisions tab being visible.

Maybe, "Thanks to Our Documentation Writers" would be better.

I like that better too. And I agree that saying "thank you" is good, especially since this block is trying to communicate two separate things at once (acknowledging current contributors and recruiting new ones). It does sound a little hokey still, but no obvious ideas for how to improve it come to mind.

Sorry David that was indeed meant for you, and I agree with your point about the links/usernames- although I'm on the 'preferring not to get credit for pages I've had little to do with' end of things.

I'm still -1 on 'thanks' in a block title - we don't have "thanks to our bug reporters" "thanks to our #drupal-support responders" or "thanks to our contributed module maintainers" on any of pages like that. For me the issue is who's doing the thanking - is the Drupal community thanking itself? Is it some unspecified entity like 'the developers' that so many newbies refer to? And when it's combined with the 'please help us' bit it looks a bit like "Thank you for not smoking" ;)

What's wrong with just 'Join the documentation team'? Then the list of names becomes a list of some people who did.

@catch "Join the documentation team" strikes me as rather cold and too understated. People, except maybe hardcore ubergeeks, have emotions and many decisions are made with those emotions. So an appeal with a little more emotion in it would help. I'm sure you've listened to fund raisers where they try to tug on the heart strings a little.

We don't have to go overboard, but some language in there that shows appreciation for the work of volunteer documentation contributors would be good. We should also appeal to people's selfish motivations (feeling good about yourself, getting credit for your work, etc.)

I'm sure you've listened to fund raisers where they try to tug on the heart strings a little.

Yes I've seen them. They lower my opinion of whatever organisation is raising the funds and make me less likely to give them any money. If they have to manipulate emotions to get contributions there's something wrong. I get loads out of contributing to Drupal - learn things, makes running my own sites easier, get to impact on bits of development and infrastructure. Thanks is about the least thing on that list, and to me it's simply a courtesy to say thanks when someone does something specific, and loses it's value when applied generally.

We shouldn't use what appeals to you or me as the basis of what language goes in the block. We should use what we know about humans and human nature in general. Again, we don't lay it on thick. Everyone hates that and sees through it. Acknowledging the human component in people is important to any appeal.

It seems to me that the most important thing to get across is information on where to go to become a part of the Drupal documentation community.

It took me nearly a month to realize that the mailing list for docs issues is the place to go to track docs activity, and that's not because I wasn't looking at first. I found the "Contributing to documentation" page at http://drupal.org/contribute/documentation when I was looking for a way to make a change to an existing handbook page, and so, following the instructions I read there, I submitted an issue with my change included, but the issue just sat there for weeks until I realized I should pipe up about it on the mailing list. That page seems to very strongly urge people to submit docs issues rather than emailing the list but now I'm not sure why.

The experience makes me think that most of the Drupal documentation activity happens on the mailing list, and perhaps that's the place that should be more prominently displayed in any block that tries to get people to join up in documentation efforts…?

@ meitar, Actually the docs mail list is important for discussion but not for joining the team nor necessarily for getting issues addressed. Your particular experience is not the usual process. Typically issues to join are addressed within a week or so. We only have 2 people who have perms to do it. Sometimes an issue will slip through on them. Issues for work can get more discussion on the list because there is not a lot of activity there (which is fine since it is more for meta discussion than tasks) but that isn't where every issue should be dealt with. The issue queue is the better place for that. We just need (a lot) more people actually watching the issue the queue.

Regarding this block generally:
I think that the title should be something very simple like "About Drupal documentation". If people are interested in the docs page, where it came from and how to effect that, that title is about all they need. The links listed under direct them to get more info and/or take action as desired. If I wanted info on how to *do* something or learn about something, a title that says thanks to some group I'm not part of doesn't really draw me, frankly. But if I saw stuff on the page or had a general feeling of Drupal docs being off, then a block that was "About" it would draw my attention.

It's a shame this issue died down - I still think this is a great idea. And "About Drupal documentation" sounds wonderful for the block title.

What is the next step here? If someone (e.g., me) were to try to put together final text for the block (probably two slightly different blocks, one for anonymous and one for authenticated), based on the above discussion, do we think it will actually make it onto drupal.org?

tagging for redesign since we should look at this in light of what MBD has given us.

Just for reference from the redesign, all they have around this topic is a block on the docs landing page titled "Help us write Documentation". Nothing on individual pages except Drupal lists and an ad block. You can see the mock here: http://drupal.markboultondesign.com/iteration11/documentation.html We can probably take some liberties with how we actually implement this.

I'm not all that pressed about implementing this now (I hate the overcrowded blocks on handbook pages already) but if folks would like, we can give the #15 draft a whirl and use the MBD title.

Linking this from the Redesign project #661566: Meta issue for Drupal.org webmaster project because this issue was tagged 'drupal.org redesign'

Not part of the redesign

stealing this to the docs queue, since we were discussing this at our meeting on friday and may want to review further

We actually have a concrete proposal for a block to be shown on all doc pages, on:
http://drupal.org/node/810508#comment-3835614
so I think I will close this issue up as a duplicate.

Just for reference, one of the principles of the redesign is that blocks must be context-aware -- we don't have any blocks that show up everywhere. The block proposed on that other issue is fine, because it is context-aware and is snappy. It is not as verbose as what was proposed here, but it fits with the redesign philosophy and serves the purpose of asking people to help and letting them know about the doc team.