Documentation Team
Welcome! This group is the main location for news and discussions about what Drupal community members are doing to improve Drupal documentation. If you join this group, you'll be signed up to receive email notifications; you can change your preferences on your account page. You can also subscribe to posts via RSS (check the sidebar of this page), and via email using the links at the bottom of this page.
The Documentation Team leadership also puts out quarterly status posts that appear in the Drupal.org home page news (these posts are meant for the entire Drupal community, not just the Documentation Team). The Drupal.org home page news has an RSS feed too.
You can find more information about how to contribute to documentation on Drupal.org. There's also information there about the Documentation team leadership and other means of communication. Join us!
Seeking Assistant or Co-Leader for Docs Team
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.
Docs office hours Tuesdays
Hey Team -
Docs office hours have been such a success, that I'm going to just set this as a weekly event rather than keep posting single events to g.d.o. I'll try and tweet reminders every week as well from @drupaldocs.
I (and often Jennifer) will be holding "Office Hours" on IRC from 1-2pm PST Tuesdays. Anyone who's working on the current Sprint or anything else that you need feedback on, please do come to IRC to ask question or request peer reviews.
Docs topic sub-groups
We've been talking for a while about the need to work on dividing up the documentation and docs issues into topic areas that people can focus on more easily.
Before Christmas I went through and tagged most of the issues in the queue (where appropriate) with any topics that seemed to come up repeatedly. It would be fantastic if people could self-organize around these tags a bit - following that tag in the queue and working on/reviewing issues - momentum getting stuff done speeds up incredibly when there's even a couple people tag-teaming!
Sprint for February: Documentation Issue Cleanup
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.
Perl script to automatically format docblock text
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!).
Tool recommendations for documentation page editing?
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!
To Sprint or Not To Sprint (at DrupalCon)
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".]
Docs Infrastructure (navigation, layout, tools) discussions of interest...
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.
Better time for Docs Office Hours?
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?
Stepping down
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
Association is prioritizing site builders...
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
API docs for contributed modules
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.
what about dynamic tables (views?) for module comparison?
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?
Template for Contrib documentation
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?
Core API documentation issue squad needed!
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.
One More Week Left to Submit Sessions for DrupalCon Denver
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!
API docs sprint!
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!
Identify and document externally-developed files which should not be changed to conform to Drupal coding standards.
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.
Standard needed for what is a "disruptive" patch
<
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
Clarify scope of PHP coding standards for core (major version) and contrib code
Posted by sun on October 1, 2011 at 8:09pm:
Problem
- Uncertainty about when or how to apply coding standards across Drupal core versions and core vs. contrib code.
Goal
-
Clarify the scope of coding standards with regard to:
- major versions of core
- core vs. contrib code
-
Explicitly specify/state which particular coding standards have been different for earlier versions.
