build2be/com/e something is going on over there

I'm about to tackle a modest project in the Accessibility pages and just wanted to be sure I wasn't reproducing anyone else's work. Anyone here working on those docs? (Our Accessibility group actually is coordinating a project to improve that content. I am plugged in with [the rest of] them.) If so, please touch base with me so we can collaborate.

Documentation Team

Start:  2010-08-27 09:00 - 17:00 Europe/Copenhagen Sprint

There will be a room set aside for Docs Team at the DrupalCon CPH code sprint tomorrow. I will do my best to be there for the day (stomach permitting), but in case I am very late (or only join virtually on IRC) or anyone is looking for an outline of what to work on, I thought it'd be good to put up some info to get started with if you are planning on attending. If you can get through prepping all of this before the sprint, you will have a head start once you get there, otherwise you will likely need to go through this info when you're getting started!

Etiquette

Take a deep breath - nobody is going to bite you... probably. ;-) Sprint day is fun and full of learning opportunities! That said, the developers will be hunkered down in groups around the sprint, so if you are working on documenting something that is related to their work, don't be scared to go talk to them. That said, they will be fairly focused and may not want to break their focus, so don't take it personally if they aren't able to stop what they're working on right that moment!

If you are new, best to sit near a more experienced Docs Team member, or with a developer who you can ask technical questions to, or even work on docs for their module/theme/part of core.

Orientation

Before you get started, if you don't have a lot of experience contributing to Drupal, I highly recommend watching this great video of David Strauss' (who is incidentally flying in for the sprint) session about contributing at DrupalCamp Dallas. It is an excellent crash course in how things work and how to get started, and covers most of the basics like IRC, issue queues, etc. If you don't watch it beforehand, I will probably just recommend you watch it when you get to the sprint!

There is also a ton of info you can dig through on the Contributors Guide

What you can help with

I'd love for us to focus on D7 docs priorities! If that seems daunting to you though, search the Docs queue for the Novice tag, or work on rolling comments (a necessary task that never gets enough attention!) - the list of pages with the most comments is here.

If you want to work on code documentation, you will need most of the tools below. But you can work on documentation that is on Drupal.org just via the web interface. You will still need to be able to install D7 and any modules you are working with somewhere if you're doing anything related to D7 docs so you can be sure your documentation matches what is happening, but it's not necessary to have it set up locally or to have command line access.

Aside from the Doc Team links that you will get in the sidebar on Drupal.org, here are some of the most useful links to get started working on documentation:

• High priority D7 docs to-do list
• Handbook Style Guide
• Getting started with Docs
• How to contribute to Docs
• Docs maintenance tasks
• Pages with comments to roll
• Docs Issue Queue

Tools

There are several tools that will be useful to set up:

IRC

IRC is the text based chat client that the Drupal community uses, and it will be quite handy during the sprint if you have an IRC client installed and working so you can communicate with the other people there, and anyone who is joining the sprint remotely. Docs sprint will be communicating mainly in the #drupal-docs channel.

There is a ton of info on how to set up IRC on d.o.

Your Drupal.org account

Be sure you have signed up for a user account on Drupal.org and then log in and go to your account (make sure you are on Drupal.org, not groups.drupal.org), click on the edit tab, and then check all the boxes in the block configuration section. This will give you some new blocks in the sidebar with links that are handy for accessing the issue queues. (This is reviewed in David's video as well.)

Setting up your dev/testing environment

To work on Drupal 7 Docs, you will need to be able to install and run a fresh version of the D7 HEAD (ie. the most up to date development version of the codebase) to do testing. This can be on an external server if you have command line access to one, but most developers will run Drupal locally for testing/development purposes - running locally = installing a server on your laptop.

There are instructions on how to set up a local server, so try your best to get through the set up before the sprint. If you are on a Mac, the most straightforward approach is to set up MAMP - these are great instructions to walk you through it.

Depending on how in depth you're going to get, if you are on Mac, you will also want to install Mac Developer Tools (Xcode) - this install is kind of large, so please do it before hand as it takes a while to download! (There are more detailed instructions here about installing and configuring Xcode, but depending on your level/fearlessness you may or may not want to delve in that intensely!)

Using command line

Scared of using command line? Well, no time better than the present to face your fears! Of course you can do testing by manually clicking and downloading, and moving files around, but that is going to be painfully slow. On Macs you will have an application called "Terminal" that will allow you to use command line to quickly update your code, make and change permissions on files, etc.

Here is a great how-to for command line but I think it is only for unix/linux.

A text/code editor

This is not necessary but it is a good idea to install some sort of text editor as well, so that you can open up the code and look at it, easily edit HTML, etc. There are several listed on this page. I use TextMate, but it's not that great. I know a lot of people like Komodo and Emacs, but what I can say about TextMate is that it has few bells and whistles, so it's pretty straightforward to get started.

Ok! I think that should do it for now! Try and work through as much of this as you can, and I will do my best to help out at the sprint, and I'm sure there will be a couple other people around who can also help out getting you on track. Come out, it'll be fun, and we definitely have a lot of work that needs doing!

Documentation Team

With a quick run-through of the program, I didn't see any talks of BoFs related to documentation on the CPH site.

I'm very interested in starting to help out with Drupal documentation, and I know there will be a need for a big push with D7. I'm just not sure where to start. I was hoping to meet up with some people in Copenhagen to give me a quick primer and sketch out some of the areas most in need of work.

Documentation Team

Introduction

A couple of weeks ago we launched Modulecraft an awareness & fund-raising project that aims to rally Drupal professionals around a shared effort to create the ultimate toolset for Drupal business. The first fundraising round has as goal the development of a documentation distribution for Drupal that uses a similar approach as the localization server and that enables a distributed/federated documentation architecture for the Drupal project. As a Drupal user you'll be able to get a set of documentation from the drupal.org docs server imported into your own site. You will than be able to edit it and build subsets of the documentation for your own projects. You'll also be able to submit topics that were edited or created by you on your own infrastructure and add them as suggestions to the Drupal documentation server.

The following is a first proposal for the specification of the Documentation system we want to build as part of the modulecraft project. It is by no means complete, and it strongly needs your feedback. This is our first encounter with DITA and our ideas should really be proof checked by technical writers that have extensive experience using DITA. It also contains some proposes a somewhat exotic usage of RDFa, feedback is also very much needed here. In the coming days I'll be adding new sections to the specification here. This is a wiki so be bold! You can add comments either here or at the original posts on the Pronovix blog. I'll be incorporating feedback into this wiki.

Why DITA

Several people from the community have indicated DITA as the ideal architecture for a new redesigned Drupal documentation.

Darwin Information Type Architecture is an open XML standard curated by the Oasis consortium that was originally developed by IBM. DITA was built to enable single source documentation: you make one central set of documentation topics that can than be reorganized in new so-called DITA maps to serve a different documentation purpose.

Drupal needs single sourced documentation: this would solve our current need to have 1 documentation structure that needs to serve all purposes and that needs to include all topics. We could build DITA maps for different user types, distributions, projects, etc.

There are existing tools that can than convert DITA output into a number of formats.

Store as XML or XHTML

DITA is currently mostly managed in a dedicated tool that directly edits the XML. To display the documentation afterwards on a website it needs to be converted to XHTML. Drupal has some tools to work on XML, but since Drupal is mostly used to publish HTML, these tools (e.g. XML filter) are few and little tested.

Storing everything in 1 XML formatted text blob would make it harder to edit the documentation and would require to either edit in XML or periodically convert back the changed XHTML back to DITA (IMHO this defeats the whole purpose of single sourcing). Since in 90% of the time we'll be working with web content it's better to store in XHTML and convert to DITA only when needed.

Using fields to simplify the interface

Adding a fixed set of fields to a form makes it easier to enforce/simplify the input of structured data. Using the Drupal (CCK) fields system to build those parts of the DITA structure that are main sections of a topic (e.g. title, description) will make it easier for people with less experience working with DITA formatted information to use the format. Inside these fields we can than use a markup editor (could be WYSIWYG or something else, see later article) to add the 'freestyle' markup, that can be added inside those main containers (only offering valid markup options).

Potentially such a system with CCK and an interface that allows for the creation of new tags could make it really easy to make specializations (this is what the D (Darwin) in DITA stands for: evolutionary extensibility of the basic topic types). If there is budget and sufficient demand we could potentially make a system that automatically derives the definition/specification of custom DITA topics from the CCK/markup settings.

Using RDFa to add not always present XML elements

DITA (specialized) topics have elements that are primary branches in the XML tree that if present are used once and mostly on the same place. Concepts have for example a title, a shortdesc, conbody and related-links. The task element has for example the taskbody that in turn contains the prereq (prerequisites) and steps element.

The step element however has several useful child elements that are not always required and that are more free-form in their use e.g. the info (additional information about the step), stepxmp (example that illustrates a step), substeps, choices (the user needs to choose one of several actions) and stepresult (expected outcome of a step).

These in-field elements could be added using an RDFa vocabulary that we derive from the DITA markup. That way we would in the first place create valid XHTML that can be converted to DITA when it needs to be exported. The RDFa markup could be applied using a specialized WYSIWYG editor that is context aware (so that only valid child elements are added).

Open Learning and Collaboration Portal

Apologies in advance for this crossposting to 11 groups. I recently started an issue to help us get to know each other better: Add field for "Memberships in Associations, Societies, and Other Professional Organizations" to User Profile. The initial response was, "Don't see why not, but let's hear more support before we do." So this is an appeal to read the issue and consider giving it your support.

This is especially important in some of the more specialized groups — do I answer this question as if I'm talking to an SEO expert, or does this person need to know the background that they skipped over? To a great extent, being able to see their professional affiliations will answer that for me.

Another way it could help is to identify specific Drupalists to target for a BOF at any upcoming event. As a hypothetical example, maybe someone is not in the Design and Information Architecture group, but is in the IxDA. Shouldn't we be sure they know about any Design BOF that is being planned?

This new field would appear under "Work" and would be at least a text field so you could enter any membership you have that you feel is significant to your online activities in general or your activities with Drupal in particular. Ideally, the field would accept html, as does "Companies worked for," so you could link to the website of each group or association you list.

As with any other fields in the profile, no one would be compelled to complete this one. It would simply be available to anyone who felt that it was useful to share this information with others in the Drupal community.

Please take a few seconds to give your support to Add field for "Memberships in Associations, Societies, and Other Professional Organizations" to User Profile.

Drupal for State and Federal Agencies / Government

For anyone needing motivation to get involved with Documentation -- NOW -- check out Ariane's post: http://drupal.org/node/876170

Documentation Team

Looking for "Volunteers for a More Visual Drupal" can you help us organize a crowd? http://ow.ly/2o21f

Would you like to help make Drupal documentation more visual? Communicating Drupal visually will be a chance to create some good contributions to Drupal.org and the community.

We need a few good people on the day of DrupalCon in Copenhagen to help organize a fun workshop. My co-presenter, Stella Power, had an argument with gravity, and lost! Wish her a get well when you see her :)

The presentation is in two weeks, Wednesday 25. August 2010, Time: 10:00-10:50

Please read more about what we need help with: http://ow.ly/2o21f

Documentation Team

Neil (drumm) just responded on an old issue I'd filed, http://drupal.org/node/780982 - I've got enough occupying my brain that I don't think I'm the right person to be tracking stats, but I thought I'd post here in case anyone would be interested in trying to get access to Google Analytics, and occasionally checking in on stats to see if there's any useful info about oft-used handbook pages and such.

If you are interested, drop a note here and we'll see if we can get access to the analytics account.

Documentation Team

I'm going to be working on a push for help with the D7 docs in the next little bit and thought it might be helpful to register a proper Docs Twitter account https://twitter.com/drupaldocs to announce sprints, ask for help with specific tasks, point out major discussions that happen, etc.

If anyone else wants the password so they can use the account, just send me a message or ping me on IRC and (as long as I know who you are) I'm happy to have multiple people use it.

Documentation Team

Hi all,

Most of us is very enthusiastic about the user experience improvements for Drupal 7. The restructure and renaming is very welcomed and I am sure it will make it much easier for newbies to get started.

There is though one area that I still see as untouched, namely the Modules list page. After installing a number of modules it is quickly becoming a bit of a chaos list, especially since a lot of modules aren't using the "package" field in the [module].info file and thus their module end up in the Other category.

Making this page better organised is actually very simple, we just need to get an official guide for module developers to follow when using the package field in their module. That's it, a single line in the .info file is all that it takes.

I have written a short Proposal: Module Category Guide for Drupal 7 post as something we could use as a start for such a guide.

Any feedback on this is welcomed. If this is of interest I can turn my proposal into a guide on d.o.

Documentation Team

This summer, we are doing a project in which we learn Drupal/Open Source skills while helping gardening initiatives. Participants will build Drupal projects that foster "Garden Storytelling." Technically, we might create: recipes for Drupal sites, glue modules, and simple sites that act as web services. Our audience is primarily Drupallers & Community Gardeners. There are about 40 participants overall, half of whom are already involved with Drupal in some form.

An important part of what we will be learning will be documentation.

We are looking for folks from the Docs team who might be interested in participating. There are opportunities to teach a small class on documentation, practice a documentation presentation on us, review documentation style and suggest how we might improve, or simply be available to answer a few questions.

We will introduce documentation early in the summer (early July,) and then practice it as we write code and learn how to do things in Drupal. Near the end of the summer (sometime at the end of August) we will do peer reviews of the documentation we create.

If you would like to get involved, please contact Chach Sikes (chachasikes@gmail.com)

Drupal Open Garden Project: http://garden.localbiology.org
On Twitter: opengardenproj

Documentation Team

Deadlines for submissions to DC Copenhagen are approaching...

In addition to BoFs, I wondered if other people might have ideas for submitting sessions at DrupalCon Copenhagen to get people interested in Documentation, or make contributions to documentation, in addition to the sprint model?

I proposed a session which will first talk about how to communicate ideas visually, then we'll look at some tough Drupal concepts new users struggle with, and we'll actually make stuff. That 'stuff' can be contributed as documentation or used by others to help teach/evangelize Drupal.

http://cph2010.drupal.org/sessions/communicating-drupal-visually-lets-ma...

So rather than a sprint, it's a little more focused and organized. And people walk away with an understand of using visuals to express abstract ideas and processes.

Maybe other Docs team people have ideas? Off the top of my head:

• Module documentation: Creating good README.txt files
• Best practices for Documenting your module on Drupal.org
• Using Advanced Help with your module
• End-user documentation: how to prep docs for your clients

We can teach some good practices of technical writing or documentation - and then in return also improve document on d.o.

Any other ideas?

Documentation Team

Just had a bit of a lightbulb moment (and maybe this idea has come up before?) about how to eventually kill comments on handbook pages. Someone asked how we could make sure conversations about a particular page were still visible if they were happening in the issue queue instead of as comments.

I thought, and this is what seemed like a good idea:

• add a field on the issue node-add form for a referenced d.o NID (to reference the handbook page the issue is about)
• build a view block for the handbook pages that displays any issues related to the page

Ta-da?

Considered filing an issue, but thought I'd get a sanity check here as to whether that would seem like a good solution.

Documentation Team