Aside from general docs work, like the monthly challenges and our current projects, my main priority the last few weeks (and into the foreseeable future) is getting a new Help system into Drupal 7 and making it kick behind. The patch to get the base system in is very close and we just need a bit more work to tip it over. Drupal 7 is aiming to be one incredible release and it is now time to really focus hard on things to make it useful to mere mortals: usability and documentation. If you care at all about the everyman in the CMS drama, then it’s time to put on yer grown-up pants and get to work.
What needs to be done right now
Currently what we really need are reviews and feedback. Here are the major pieces we need eyes on:
- There is a demo site that will let you play with the new system as a site admin. You can see the inline pop-ups in action and get a feel for the topical organization. How does that feel? Anything odd or unexpected?
- Look at the help files themselves. We have two kinds of files needed: one is a .help file and the other are the HTML files. They both have particulars about how to use them. Read the Help module’s help pages (you need to be logged in to the demo site) and then look at some real examples. Grab a .zip of the core module help files. If you were going to write up a few help pages, how well do you understand what you would need to do?
- Review the code. We need the patch itself to be gone over with a fine-toothed comb so even if you are just nit-picking on comments in the code or find variable names confusing, we need it.
Once you’ve done some review and you have feedback about the code or the UI, leave a comment on the issue. If you don’t like something, make sure you also include details about what you expected instead or alternative suggestions. This will make your feedback constructive and help everyone keep momentum for pushing things forward.
Wait, why do we need a new Help system?
There are a two particularly big, glaring holes in Drupal’s current help system: it requires mucking with PHP files and it is tucked away in a place that no one ever goes (hence the text itself is generally pretty neglected too). I mean really, how many people reading this right now regularly, if ever, click into the Help section of their Drupal site? Do you even know it’s there? We need to provide help text to users in context of what they are doing and at the same time not overwhelm them with small tomes of tiny help text under every. single. form. field. Inline, contextual help is what all the cool kids do and they do it for very good reasons. It stays out of the way when you don’t need it, but it is right there, in full, when you do.
The fact that our help text is inside PHP files makes it hard to read, hard to organize and frightening to edit for many people, where an apostrophe out of place might actual spit fatal errors. A lot of people who can contribute a lot to documentation efforts can get by feeling a little edgy when they write in HTML. Pushing them into PHP means you simply lose them altogether. We have lost a lot of very good help in explaining things because the barriers are simply too high. Even if you do manage to get in to the text, there is still the matter of organizing it using a URL-based system. Our current system isn’t very flexible or friendly if you want to have several organized, hierarchical pages on a topic. Ook. The chunked-up PHP text that we use also makes it a real PITA for translators to get into a flow and stay in context. Getting help text into large pieces of coherent text using HTML makes it easier for documenters, easier for translators and easier for regular folks to simply access and read it, straight from the source if needed. If you’d like to read a bit more, you can read this about.html file directly from the demo site’s Help module directory, explaining why Earl Miles created Advanced help module, which was the catalyst for this new core patch. Cool, huh?
Sweet, so what happens once this gets in?
Once we get this patch in to core, we have a few follow-up issues already waiting in the wings to keep hammering on it and making it better. We will also need to review the existing help text we have for core modules and with the new handy-dandy system we can easily expand that documentation. This new system also opens the door to provide additional documentation modules for topics like upgrading your site and lots of general “you just installed Drupal, now what?” kinds of help. So, we need to get the base system in as early as we can, so that by the time Drupal 7 ships we will have not only awesome documentation, but it can be included right inside your Drupal site.
RockTreeSky 