Documentation

Our next weekly Documentation Office Hours will be a discussion of how we can push forward with the plans for the "Curated Docs". Other Documentation Infrastructure discussions would also be welcome, but I'd like to concentrate on the Curated Docs. Please sign in and join the discussion!

See above for the time (hopefully in your time zone; if not, check your user profile). The discussion will take place in the #drupal-docs IRC channel.

It's great when we get newly injected energy into usability efforts in Drupal, as happened with the Drupal Usability Study at Google last week. However, these patches always run aground of various "freezes" we put in place in the stable release of Drupal:

API freeze

Don't commit patches that break backwards API compatibility within a stable release, for the benefit of contributed module and theme authors.

String freeze

Don't change any user-facing text (e.g. anything in a t() function), for the benefit of translation teams.

UI freeze

Don't commit patches that affect the user interface, for the benefit of the documentation team, as well as to not invalidate tutorials, screencasts, books, etc.

Feature freeze

Don't commit patches that add new features; stick only to bug fixes. Additional functionality gets added in contrib.

As far as I can tell, these guidelines are not actually written down anywhere, but simply passed down word-of-mouth from core generation to core generation. I want to do two things in this thread:

1) Create documentation around these guidelines.
2) Propose that we change these guidelines to make them looser and allow more classes of patches to be backported, particularly minor UI tweaks and string improvements.

Here's a proposal (co-developed by Dries, Moshe, Alex, and I), with the items in bold being ones that we propose to change, the rest being documented to the best of my current understanding. My hope is that this can both help is iterate faster on the core product, and also provide additional incentive for people helping with Drupal 8 core development, as there'd be a chance of them seeing their changes in a version of Drupal sooner than 18+ months away.

Hello Documentation Team!

As you probably have noticed, the Documentation Team is no longer taking full responsibility for maintaining/writing/editing the Community Documentation (recently renamed -- http://drupal.org/documentation). As part of the effort to move this responsibility out of the Documentation Team and into the Community at large, we are mostly trying not to use Documentation issues to report problems. Instead, we're encouraging people to edit the pages directly, or at least add a comment and change the page status.

One of the things that I find really fiddly with writing documentation is making sure lines wrap to 80 characters. I find it really breaks my flow of concentration to be always watching for when to hit return or even go back when a word turns out to be too long and then type a space-star-space (how on earth people did it in the days of manual typewriters... I guess we're just spoilt with technology nowadays!).

I was tweeting @drupaldocs yesterday, which is now leading to me posting here. Observe:

Me: @drupaldocs Can you recommend any tools/browser plugins/etc. for quicker/easier editing of docs? Maybe outliners, and so on? #drupal
@poplarware: @wizonesolutions @drupaldocs I don't know of any... maybe another Docs contributor does -- you could post on our g.d.o group with more info?

So here I am!

The Documentation Team has traditionally hosted a documentation sprint at all of the North American DrupalCons, and this past year, also at DrupalCon London (I'm not sure if there were sprints at earlier European DrupalCons or not). [If you're not familiar with the term "sprint", the DrupalCons usually have a day, either just before or just after the main DrupalCon event, where people get together and work in a big room, and we call that a "sprint".]

You may have noticed that the big "Rename Documentation to Community Documentation" change happened recently -- if not, check out http://drupal.org/documentation and especially individual documentation pages such as http://drupal.org/requirements , to see the new layout.

We've been having weekly Docs Office Hours for a while now, on Tuesday at 1pm (US/Pacific time) -- see http://groups.drupal.org/node/145039 for more details.

That particular time/day was chosen because it worked well with Ariane's and my schedules, and seemed like it might be good for others as well. But I'm wondering if people would prefer another time? My schedule is fairly flexible (within the constraints of my time zone), and I'm open to changing the time.

Post comments/thoughts here... if no one has a strong preference, I'll probably leave the time as it is. Thoughts?

Ariane has just officially left her position as the co-leader of the Drupal Documentation Team, leaving me as the sole leader (see http://drupal.org/node/1402190)... I've agreed to stay on as Leader for the time being, but since I've been acting in a leadership role in the Documentation Team for a couple of years, and with the official title for more than a year, I'd like to put a time limit on my tenure as Documentation Team Leader.

Hi Team!

Some of you may have already heard through the frontpage or Twitter, but the announcement has just gone up that I'm stepping down as Docs Co-Lead: http://drupal.org/node/1402190

In case you didn't notice, the Drupal Association has made a list of 6 priorities for 2012. Number 6 is "Make Drupal.org awesome for site builders", and Documentation is a large component of this.

So I just thought I'd make sure the Documentation Team was aware of this discussion:
Original page discussing the 2012 priorities: http://groups.drupal.org/node/197558
Sub-page specifically about this priority: http://groups.drupal.org/node/198708
Association group home page (which also lists these priorities): http://groups.drupal.org/drupal-association

One thing I find conspicuously missing from drupal.org is API documentation for contributed projects. We've put a lot of effort into coding and documentation standards, and this is paying off in improving Drupal core. But we are not seeing any benefit of this in the contrib space. Contrib modules really have no incentive to provide extensive Doxygen documentation because no-one ever sees it.

I am relatively new to drupal, and i've been evaluating some Module-types like lightbox- or imagecropping- Modules.

There are quite some comparison pages, and even a list of them.
Very usefull.
But i think as static text, they will always be outdated.

So, did someone ever think about dynamic comparison tables for modules?
I'd imagine a view that can pull compatibility, installs, activity etc. directly from the projects, so they would never outdate...

Maybe that's harder than i think?

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?

For the past several years, I have been the person who has managed the documentation component of the Drupal core issue queue.

Several people besides me have recently started contributing to Drupal's API documentation by patching issues, and I'm very happy about that! What I'd like to do now is also get a few people to take on the issue queue management tasks as well.

Session proposals are still being accepted for the next DrupalCon, being held at the Colorado Convention Center in Denver, March 19 -23, 2012. The conference theme is "Collaborative Publishing for Every Device" and the deadline to submit sessions is October 26, 2011 23:59:59 UTC/GMT -7. Submit your session today!

Some of you may have heard that I wanted to organize an API docs cleanup sprint... Well, here it is:

(issue) http://drupal.org/node/1310084

The idea is to have a sprint over the next couple of weeks, and get the Drupal Core API documentation to conform better to our documentation standards. All the instructions are on the issue... please feel free to post general questions here, but otherwise, discussions about specific documentation, standards, etc. are better off on the issue queue.

Let's get this done!

Problem/Motivation

There are externally-developed files, such as misc/jquery.js and module/system/system.tar.inc that should not be updated to meet Drupal coding standards.

<

dl>

There is frustration among new developers about how to make issues and patches that cause a minimum of disruption and a maximum of ease for reviewers/committers.

So we need to make a page explaining this. Suggested outline is on the above comment, and suggested place to put it is either:
http://drupal.org/patch
or
http://drupal.org/patch/review