Discussion

Unfortunately contrib documentation sometimes seems to be few and far between. I understand this is because people are busy and a lot of people are working on Drupal modules on their own time. That being said, I think if we had a template, it would be a lot easier for people who aren't used to writing documentation and who need guidance to write documentation, and it would also bring some consistency to the documentation that is on drupal.org.

Ia anyone interested in helping me create a template for contrib module documentation?

As a (partial) follow-up to Towards Docs Sustainability... Here is a proposal (or the beginnings of a proposal) for a major structural revision to how we do documentation on Drupal.org, and to the Documentation team.

Your suggestions and ideas are welcome! Please comment below, and then I'll go back and edit this proposal to incorporate the great suggestions I'm sure you will have.

Note: This is a work in progress, and may have been edited since you last looked at it, or since someone made a particular comment... sorry for any confusion!

If you are an experienced site builder, or a medium-to-experience PHP programmer, the Docs Team needs your help! We have several things that we’d like to get done that will improve the infrastructure for documentation and for contributing to documentation in the Drupal project.

EDIT: I'm marking tasks "taken" if someone has spoken up to do them.
Update Sept 23 - new tasks added!!
Update November 15 - task list edited

Site Builder Tasks

Compiling a bunch of the ideas that have come up over the last week in discussions with the Docs Team folks at Drupalcon London. It's been a running theme that the docs are no longer manageable, and some concrete suggestions to deal with that are as follows. Note they are all options and need not all be adopted, some are exclusive of others:

Hi all,

These days we see quiet many learning series / articles coming out on drupal.
All these are getting listed under drupal planet along with other articles as well.

Can we have a doccumentation page like we have for success stories, case studies where in we all list / aggregate feeds from all these learning series (another planet kind of page but, dedicatedly contains all the learning series / learning initiatives) ?
I am sure this will improve the ease of finding drupal related materials easily for a new comer.
Right now its hard to search these within planet.

This might be a wrong group to ask, but I will try anyway :)

Why can't we have a simple link to the contributed module's README on top of the module page, beside the "Version control" link ? And a similar "Documentation link".

I've been asked to edit the Standard Issue Tags for Drupal core page to correct its characterization of accessibility issues, and, as usual, the editorial eye found more needing to be fixed than it was asked to review.

Specifically in this case, there are cases in which two issue tags are difficult to distinguish from each other. "Accessibility" and "needs accessibility review" is one such instance. Another is "usability" and "needs usability review." The definitions given for these terms don't help clear things up, either.

Before I make sweeping changes, I would like to get feedback from folks who are familiar with the issue queue about a role- and intent-based approach for telling who should — or, sometimes, who may — use any particular tag.

Before diving into this post let me tl;dr: Fostering good communication with new users.

So I asked around on #drupal-contribute to see if there was a guide for helping and guiding users who want to help out with Drupal. There does not appear to be one so here is an attempt to make one. The goal of this discussion is to create an outline which will then get folded into the Drupal documentation for mentoring users. Lets play out a scenario to show where guidelines could help.

A user comes into the irc channel and states they want to help with a project and asks "Where should I start?"

Ariane and I have been getting inquiries lately about whether we can come to various regional events to host a documentation sprint. It's always exciting when people are interested in working on documentation, and we're glad that there is so much interest in sprints -- they are a great way to get some work done and introduce new people to contributing to documentation. But unfortunately, being a Documentation Team co-lead is a completely volunteer position, and neither of us has unlimited travel time or budget (even if the regional camp offers to pay travel expenses).