Jul 01 2019
Jul 01

I'm very pleased to announce that we (hopefully) have a new help system in Core that will actually serve the needs of module, theme, and distribution developers! It is called "Help Topics", and is currently in "Experimental Module" status in Drupal core 8.8.x.

The way it works:

  • Modules, themes, and distributions can have a help_topics subdirectory in their projects, where they can write help topics in the form of Twig template files. Each project can have as many topics as they want/need to document their project.
  • The Twig files have meta-data (in HTML meta tags) at the top to define the title of the topic, whether the topic is "top-level" or not, and a list of other topics to mark as "related".
  • When a user visits the admin/help page (assuming the Help and Help Topics modules are enabled), they will see a list of the top-level topics, and can click through to read them. When reading a topic, at the end they'll see a list of all the topics that are "related" (and "related" is automatically a bi-directional relationship).

So... The module is currently in "Experimental" status, and we need your help to get it to "Beta" and then "Stable" status in Drupal Core:

This effort is being led by andypost, Amber Himes Matz, and jhodgdon... if you have questions, we can all often be found on Slack or on drupal.org.

Feb 14 2017
Feb 14
larsdesigns's picture

Sounds awesome. I can't wait to give it a run. Thank you so much!

Sep 08 2016
Sep 08

At long last, the copy editing of the User Guide is done! (If you've been a member of this group for a while, you should know what I'm talking about; if not, go browse the archives at https://groups.drupal.org/documentation for the last 1.5 years or so). I'd like to thank everyone who helped with editing tasks, and especially Jojy Alphonso (jojyja), who did the vast majority of the copy editing. THANK YOU!

So, the guide is in very good shape, and I just made an official release of version 8.x-2.0, corresponding to Drupal Core 8.2.x (which is supposed to be released soon). It should be live on Drupal.org soon, in HTML format, for your reading pleasure (not sure exactly when, since the reduced Drupal Association staff is pretty busy, but we're working on it). I'll post a link in a comment here when that happens.

Meanwhile, you can go to the User Guide project page and download the release, which contains all of the source files (which are written in AsciiDoc markup language), as well as PDF, ePub, and Mobi ebook versions (those are in the "ebooks" folder/directory of the archive you get when you download the project).

Enjoy!

Also... The next step will be to translate the User Guide into other languages. The enthusiastic and experienced Catalan and Hungarian language teams will be starting on that shortly, and refining the process so that hopefully the other language teams can get started soon as well. If you want to help translate the Guide, you should start by joining the translation team on https://localize.drupal.org for your language. Thanks!

Dec 07 2015
Dec 07
jhodgdon's picture

I'm not getting that error, but probably some time ago I told my browser to "connect anyway". We should bring that to the attention of the infra team.

jfmacdonald's picture

Connected anyway, recklessly ignoring the warning. After doing so, Chrome did not repeat the message when revisiting the page.

jhodgdon's picture

Ah thanks! I will fix the URL links in this post and on the User Guide project page.

jhodgdon's picture

Actually that URL gives me a 403/forbidden error....

jhodgdon's picture

I got clarification from basic -- that new URL is not valid actually. But we will probably migrate the site over to the new URL in the next day or two.

joebachana's picture

I'll help in the coming weeks during the holidays. Also we have the NYCDrupalCamp on Feb. 27th where we'll be doing some sprint work so if this is still (gulp) getting worked on by that time we'll enlist people in advance to work on the guide then.

Joe Bachana
First Employee at DPCI
1560 Broadway
NY, NY 10036
212.575.5609
www.dpci.com

krishnan.n's picture

Both links don't seem to be working for me.

jhodgdon's picture

You need to log in with user name drupal and password drupal in the pop-up windows.

Sorry, I often forget to say that... It does say it in the pop-up window but no one ever notices that. ;)

jhodgdon's picture

It's definitely working for me... sorry it is not working for you, but maybe someone else will confirm working or not working, and if it's not working for a bunch of people we can try to do something about it? Hmmm...

cleverington's picture

krishnan.n (I love your login name):

I tested on updated versions of Chrome, Firefox, Opera, and IE Edge via Windows 10. Out of interest, I tried it via Chrome-by-phone-Android too.

Try clearing your cache and retrying, there might be cached information that is disrupting your access to the server. If you killed the login-box by accident via the Esc key, it might have saved your 'decision' (depending on the browser).

~~Cheers!
cleverington

The man of many hats.

krishnan.n's picture

Hi,

Worked first try on the office WS; will see what the issue is with the *BSD box at home.

Cheers,
krishnan

MirosławDętka's picture

It doesn't work so far

Mogensj's picture

Is there any solution on the "Your connection is not private"-problem?

Best regards,
Mogens

MystiqueBrand's picture

We don't have any Drupal experience and could use some expertise to assist with an upgrade.

Is it true - drupal 8 has a easier to use interface?

Client is also considering moving to WordPress but I don't think it makes sense as its a non profit organization. Thoughts?

Paul Bies
416 441 2666 ext14
[email protected]

preben_j's picture

The new Drupal looks way better than the old. Good job guys. I will check if it can work with me website. Is the userguide done yet?

jhodgdon's picture

The User Guide is not quite done yet. We are close to having a full first draft with all the topics written... then it will need some editing and some work on the images/screen shots. But it is getting pretty close.

preben_j's picture

Thanks man - Will look into it when done. Will keep following this thread, if you wanna update when finished.

// Webdeveloper at https://moneybanker.no

jhodgdon's picture

Please go to:
https://groups.drupal.org/documentation
to find the latest updates. This page that you commented on is rather old; there are more recent updates there.

Also, ... this is a community project and it relies on the Drupal community to help us get it done. The latest updates outline how you can help! Thanks!

Ismanden's picture

Hey,

Ihave the same problems on my site: http://www.mikonomi.dk/

Is there anybody in here thats has the right answer, I think I have tried all the things that people suggest here

Hawkes's picture

Thanks - I will try to contribute as soon as my current project is done.
- Martin
/ Frontender and javascript developer at Finanssans forbrukslån

bluesky94's picture

Thank jhodgdon. I just changed to Drupal 8 yesterday. Hope my first new project by Drupal 8 works well!

Dec 02 2015
Dec 02

For several years now, I've been serving as the API documentation maintainer for the Drupal core project. It's a job that I enjoy doing, since it combines working with the Drupal community (especially new contributors) and improving API documentation (somewhat of a passion). But it's a pretty big job for just one person, and lately, I've been taking more "personal time" (traveling, not working a full 8 hour day, etc.), and I've had less time to devote to it. So, I'd really like to find another person or two, having at least some level of experience with Drupal core development, to share the job.

Clarification: I'm talking here about the API (programmer) documentation that you can see at api.drupal.org, which is generated from specially-formatted comments in the Drupal Core PHP source code, and modified by updating Drupal Core PHP source code.

Job description

Help with any of these items would be welcome:

  1. Triage new issues that are filed in the Drupal core project in component "documentation":
    • Sometimes they belong in a different component or a different project, and can be moved there.
    • Sometimes they are really support requests (someone needs help either using Drupal or programming with Drupal); in those cases, you can politely steer them towards the https://www.drupal.org/support page where they can find more appropriate resources (we don't handle support requests, as a general rule, in the Drupal core issue queue).
    • Sometimes they need an update to the title and/or issue summary for clarity, so you can do that.
    • Sometimes they don't make any sense, and you just need to ask the person who filed it for clarification, and set the status to "Postponed - maintainer needs more info".
    • Sometimes they are straightforward, easy-to-fix issues; in that case, add the "Novice" tag and someone will soon make a patch.
    I usually try to check for new issues in the documentation component every few days and triage them appropriately. And always say thanks for filing issues (if they're not filed, they won't be fixed!)... except for the Support requests, where a polite tone of "Sorry, but we don't do support here so you'll need to look elsewhere" is more appropriate than a "thanks" vibe.
  2. Review patches (in the same documentation issue queue) for:
    • Accuracy - does the patched documentation match what the code is actually doing?
    • Clarity - is it well-written, easy-to-understand documentation?
    • Completeness - are there more points that need to be made? Does the patch cover all of what was stated as problems in the issue title and summary?
    • Standards - does the documentation conform to our comment and documentation block standards on https://www.drupal.org/node/1354 ? Will included code examples work, and do they comply with the Drupal project coding standards and best practices?
    • Copy - punctuation, grammar, good English, spelling, etc.
    If the patch does comply with these points, mark it Reviewed and Tested by the Community. If not, mark it Needs Work, and provide detailed, polite feedback on what needs to be changed. Especially for new contributor patches, if the wording is awkward or unclear, a specific suggestion of new wording is very helpful. And be sure to say thank you to the person or people who supplied patches, and keep the tone polite and respectful.
  3. Committing documentation patches: This is part of my "Core Maintainer for Documentation" job description, but at least for now, that wouldn't be part of a new person's job description.

Skillset

The ideal person or people for this job will have the following skills and attributes:
  • Knowledge of how the Drupal core issue queue and patch workflow works (someone who has not worked on any Drupal core issues would probably not be best for this job, yet).
  • Knowledge of the comment/documentation standards (this can be learned on the job, but ideally the person will have made some API documentation patches in the past).
  • Attention to detail.
  • Caring about improving Drupal documentation.
  • English grammar, punctuation, etc.
  • Patience - many of the people contributing documentation patches are novice contributors, and you'll see the same mistakes made over and over, sometimes repeatedly by the same person. It can get frustrating, and it can be difficult to maintain a polite, respectful, thankful tone.
  • PHP coding - you'll need to be able to at least read PHP code and figure out what it is doing, in order to assess whether a patch contains accurate documentation of what the code does. This may also involve some sleuthing, such as seeing how a function is being called, how the return value is being used, or what the classes implementing an interface method are doing.
  • General knowledge of Drupal 7 and 8 (mostly 8) APIs would help, but you can definitely improve those skills as you go.

Any takers? You can jump right in on issue Triage and Reviews (as described above), without asking for permission. Or if you'd like to discuss it with me, find me in the #drupal-contribute IRC channel or contact me via my Drupal.org contact form (I'm assuming anyone who's right for the job would know how to do that -- I'm jhodgdon on both). Fame and gratitude can be yours, in just a few hours a week!

Jul 08 2015
Jul 08

For the past 8+ years, Neil Drumm (drumm) has been maintaining the API module, and I've been co-maintaining it for the past 3+ years. (This is the module that builds and displays the Drupal API reference site api.drupal.org). Both of us have "some" other responsibilities in the Drupal ecosystem, and we'd like to find a new co-maintainer.

The ideal person would be:
- A good PHP coder familiar with and willing to follow the Drupal project's coding standards
- Familiar with the api.drupal.org site and its features
- Familiar with the API docs standards
- Familiar with both Drupal 7 and Drupal 8 core code (or at least familiar with the kinds of code it contains and the Drupalisms that it has), since both are displayed on the site
Of course, all of these "ideals" are negotiable and/or learnable, and it could be that a few co-maintainers would be better than just one.

The next step would be for the person or people who are interested to start making patches for a few issues, and once a few of those have happened, we would consider making you an official co-maintainer. The project page has a link to documentation for how to get a local API site set up, and the module also has a robust set of tests. The code in the API module is somewhat obtuse, but I'd be happy to start anyone out with a quick tour (or help you find an issue to work on). The module runs on Drupal 7 only at this time, and this is unlikely to need to change anytime soon (it displays Drupal 8 code but runs on Drupal 7, like the other *.drupal.org sites).

So if you're interested, you can either jump in and find an API module issue to work on and make a patch, or use my contact form or IRC to contact me and discuss.

Sorry... by policy, comments on this post are disabled, since it is going into the Core group (as well as Documentation).

Jun 02 2015
Jun 02

There's a new proposal to create a coherent, internationalized Drupal 8 User Manual, which Joe Shindelar (eojthebrave) discussed at DrupalCon Los Angeles recently. Because we want comments on the proposal, it's posted in the Documentation group (the Core group doesn't allow comments):
https://groups.drupal.org/node/470648

I thought some other groups might be interested, so I'm posting this quick note to let you know. Follow the link for all the details and discussions.

Jan 06 2015
Jan 06

Here's an update from the Documentation Working Group (DocWG) on what has been happening in Drupal Documentation in the last month or so. Sorry... because this is posted in the Core group as well as Documentation, comments are disabled.

If you have comments or suggestions, please see the DocWG home page for how to contact us. Thanks!

Thanks for contributing!

Since November 28, (our previous TMIDD post), 232 contributors have made 733 total Drupal.org documentation page revisions, including 8 people that made more than 20 edits (lolandese, Francewhoa, webchick, kreynen, YesCT, Pierre.Vriens, Wim Leers, and PsyCode) -- thanks everyone! Most of these people are seasoned Drupal contributors, but PsyCode is a Google Code-In participant who has been editing pages. That's great -- we love it when our old friends come back to help, and when new people get involved!

In addition, there were many many commits to Drupal Core and contributed projects that improved documentation -- these are hard to count, because many commits combine code and documentation -- but they are greatly appreciated too!

Documentation Priorities

The Current documentation priorities page is always a good place to look to figure out what to work on, and has been updated recently.

Of special note: We're trying to get the Help pages inside Drupal 8 updated -- check the priorities page and events section below on this page for details.

If you're new to contributing to documentation, these projects may seem a bit overwhelming -- so why not try out a New contributor task to get started?

Upcoming Events

Report from the Working Group

The Working Group meets monthly via Google Hangouts, and our next meeting is January 14. Contact Boris if you'd like to join the meeting. We're currently discussing how we and the community can address several big problems:

  • The lack of documentation for Drupal in languages other than English.
  • The difficulty of locating documentation that answers specific Drupal questions.
  • The overwhelming size of Drupal documentation for newcomers (not knowing where to start).
May 08 2014
May 08

Dries Buytaert, the CTO of Aquia and head of the open-source Drupal project, recently wrote a blog post about the business case for hiring a Drupal core contributor. Dries wrote about the measurable effect that a larger Drupal shop can realize from hiring a contributor full-time.

But what if you're a smaller shop, consisting of 1-5 Drupal experts? You obviously can't afford to hire someone full-time to work on Drupal Core development -- but you can still reap benefits from contributing some of your own time, or (if you have employees) paying them for a few hours a week to contribute to Drupal Core or another Drupal sub-project (module, theme, etc.) that many people use, or volunteering in another way (providing free training in your local area, organizing a Drupal meet-up, etc.). The main benefits I see:

  • Your own expertise in Drupal will grow, making you a better Drupal shop.
  • Your reputation among members of the international Drupal community will grow, possibly leading to concrete benefits, such as referrals.
  • Your reputation among members of your local Drupal community will grow, almost certainly leading to greater possibility of referrals and project partnernships, which a small company always needs.
  • When a client is looking for a Drupal contractor to hire, the fact that you are a contributor to the Drupal project or the organizer of a local meeting may tip the balance towards you over another Drupal shop. (A little marketing is in order: publicize your contributions on your web site, and make sure, when talking to clients, to mention your work -- it will add to the sense of expertise that a prospective client is looking for.)

And if your company doesn't have time to contribute volunteer hours to the Drupal project, you can also reap some benefits (good will in the community and good feelings from clients) by contributing financially (again, if you do a little marketing). I know of several great ways to do this:

  • Join the Drupal Association, the non-profit that does so much for the Drupal open-source project (such as paying for the servers that drupal.org and associated sites run on). Once you become a member, you can display a DA badge on your web site.
  • Donate regularly to Drupal developers via Gittip -- you could donate to the Drupal Core team or to one or more developers that works on key modules that your company uses. Once you start donating, you can display a Gittip badge on your web site.
  • Fund particular Drupal projects via Drupalfund, a crowdsourcing platform specifically for Drupal projects. Unlike Gittip, which is meant to be used for weekly contributions to individuals and teams, Drupalfund is for one-time contributions to particular projects (adding features to a module, porting a theme to a new Drupal version, etc.).

So... Pick your method, and do something to help the open-source project that your livelihood depends on!

Apr 11 2013
Apr 11

Earlier this week, I attended and gave a talk (Motivating Developers to write API Documentation -- based on my experiences with the Drupal project) at the first WriteTheDocs conference in Portland, Oregon. The conference overall was pretty good:

  • Good program (the speaker and topic selection was excellent)
  • Good food
  • Free drinks
  • The WiFi worked (not always the case at conferences)
  • Lots of side activities (hike, pre-conference meet-and-greet, parties and gatherings)
  • Portland is a great city

The only thing I thought was not so great was the venue -- which was a neat old building but in my opinion not the best place for a conference:

  • Non-ADA accessible (perhaps someone in a wheelchair could have gotten in, but they definitely would not have been able to reach the bathrooms)
  • No "hang-space" -- no one is going to be interested in every talk (and I definitely didn't want to sit through two whole days of talks even if they were mostly of interest -- brain melt!), but there was no place to be except in the main theater space.
  • Not enough tables (pretty much everyone had a laptop or paper for notes)
  • Poor lighting (theater-style lighting meant the speakers could not see the audience, making it less interactive, and upstairs you would have needed back-lit paper to take notes)

A few take-home messages from the first day's talks (hopefully the speaker slides and videos will be posted on the conference site soon):

  • Kenneth Reitz... To write a good API: Write the README file first, then the docs, then the API itself.
  • Michael Verdi... The Mozilla project has some interesting work-flow around their support wiki in regards to translations and revisions: Keep track of "helpfulness" ratings and aim to revise the least helpful docs. When making revisions, have a way to mark them as needing translation update or not. A side-by-side editor for making translations, which highlights changes since the last translation update. A way to find the most popular docs to concentrate on getting them translated first. A policy of minimizing revisions on those docs so as to minimize the need for translation updates.
  • Matthew Butterick... Typogography (font size, line length, etc.) is really important for readability. Use colors etc. to emphasize things that are actually important, and be careful not to use colors that would make unimportant things stand out.
  • Lightning talk (not sure who, sorry!)... Keep track of failed searches for documentation and use them to know what documentation needs to be written or what keywords need to be added to existing documentation.
  • Kevin Hale... Make everyone in the company/group do support from time to time, so they really understand what users go through.
  • Nisha George and Elaine Tsai... The Support team can/should own some documentation.
  • Brandon Phillips... Set up documentation so you don't have to click through so many layers of navigation -- single-page documentation. But Kevin Hale commented that for novice users, this style of documentation is overwhelming according to his usabilty testing.

I ended up leaving after the first day due to my brain being overloaded and a lot of work to do, but I just wanted to say thank you to the organizers, speakers, and sponsors!

Jan 10 2013
Jan 10

I finally got a copy of my new book, Programmer's Guide to Drupal in the mail yesterday -- it's very satisfying to see it in print. Maybe you'd think someone who makes her living almost entirely by electronic means would stick to e-books, but ... call me old-fashioned, but I still do like reading paper. So, while e-books are poised to outstrip paper books (especially for technical books) any day now, I am glad that my book is available in paperback too, and it's tangible and very satisfying to hold.

I thought this might be a good time to reflect a little on my experiences with the publishing process, now that the book is out (I expect I'll be doing revisions as time goes on, including a major update when Drupal 8 comes out, but for the moment I'm done). Overall, I have to say that the experience of writing a book and publishing it with O'Reilly was positive:

  • I have always liked doing technical writing, so I enjoyed the writing process itself.
  • Of course, I am quite enamoured with both programming and Drupal, and I have a great interest in technical documentation, so I was quite passionate about the subject and about conveying the ideas I put into the book. That was what kept me going.
  • I had a great editor, Meghan Blanchette, who supplied me with very constructive suggestions and quick answers to all of my questions (this was the first time I had ventured into the publishing world, and it was all new to me).
  • O'Reilly has several options for authoring software, and the one I chose (AsciiDoc) allowed me to do the writing in a plain-text editor and submit changes using Git. This meant I could write the book using the same tools I use every day in my professional and volunteer Drupal work. AsciiDoc was easy to learn and intuitive, and for the most part enabled me to just concentrate on the content.

There were only a few not-so-positive aspects to the experience:

  • The O'Reilly AsciiDoc system had a few glitches and bugs here and there, which occasionally stood in the way of writing. The Tools team at O'Reilly fixed the bugs and answered my technical queries pretty quickly, though, so this wasn't a huge problem.
  • My account in the O'Reilly Author Portal was not set up correctly initially. There's a lot of good information in the Author Portal that I didn't have access to, which would have helped me feel a little less lost in the publishing process, and probably would have meant a lot fewer questions to Meghan along the lines of "what happens next?". Unfortunately, I didn't realize this until way at the end of the production process (how would I know what information was supposed to be there?). So... If you start working on a book with O'Reilly and you don't see a "Welcome Kit" in the author portal, ask about it!
  • The proofreading step in the final publication process was ... painful. I'll leave it at that.
  • I felt like communication kind of broke down during the final publication process, when Meghan handed the reigns over to the Publication department. I wasn't kept very well informed about the process (again, having access to the Welcome Kit would have helped if I had known!), and strangely enough, no one emailed me at the end to tell me we were done and my book was out (I found out by accident via Twitter, which I barely use). This left me feeling like the process was a bit out of my hands (which I guess it was, to some extent) -- quite different from the earlier steps when it was mostly up to me.

All in all, it was a positive and very satisfying experience! I'd even consider doing it again, and I'm certainly, on balance, looking forward to rather than dreading the major revisions that will be needed for the Drupal 8 edition, hopefully sometime later in the year. If you have any ideas for other Drupal books that need to be written, drop me a line!

Dec 13 2012
Dec 13

My new book -- A Programmer's Guide to Drupal -- is officially published, just in time for your holiday shopping needs:
http://shop.oreilly.com/product/0636920027799.do

The writing and publishing process was an interesting break from my usual Drupal site building and programming work, and I enjoyed it. Working with O'Reilly was great, and I'm thrilled that the book is finally done... at least for now. I expect to be doing revisions for a second edition when Drupal 8.0 comes out (sometime next summer or fall).

In the meantime, I hope that my book can help some aspiring Drupal 7 programmers to ramp up the learning curve more quickly than they would otherwise!

Nov 16 2012
Nov 16

During each Drupal major version cycle, there is always an effort to identify major contrib functionality that could/should be added to Drupal Core, and Drupal 8 is no exception (can I just say: VIEWS - HOORAY!!!).

One of the most-used and most-downloaded contrib modules is Pathauto (http://drupal.org/project/pathauto), and there has been an effort several times to get it into Core.

With your help, this could become a reality -- but only if we act fast: there are several tasks that need to be taken care of before the upcoming Feature Freeze (which is scheduled to be December 1st -- see http://buytaert.net/updated-drupal-8-release-schedule).

What can you do to help?

You can sponsor development resources, work on patches, review them, etc. Here are the tasks that need to be done first:

Once that is all done, the automatic URL alias functionality can just be an alternative widget for the path alias field, which should not be difficult to create, and then the only remaining step will be to add a few sensible defaults to the standard install profile, and we'll be good to go!

So.... step up now!

Jul 18 2012
Jul 18

For the past 18 months or so, I've been the official leader or co-leader of the Drupal project Documentation Team, and I've been an active member and organizer for several years more.... Today I announced the end of my tenure in that role in the Drupal community, and I wanted to say a few words about my plans.

First off, I want to be clear: I'm still planning to contribute a lot of my time to the Drupal project! I will be staying on as the Documentation Maintainer for Drupal Core, so I'll still be reviewing and committing changes to the Drupal Core API documentation. I also plan to keep maintaining the modules on Drupal.org that I'm currently maintaining, including the API module (which runs the http://api.drupal.org site), and to keep working on improving other tools and infrastructure on Drupal.org for documentation and programmers. These are all fun tasks for me, and I also feel like my contributions in these areas are very well appreciated by the Drupal community, so I see no reason to stop contributing in these ways.

On the other hand, the role of "team leader" had evolved to a point where it was not as much fun for me, for a couple of reasons. First, one of the main responsibilities of the team leader is to recruit, motivate, and retain team members to write and edit documentation -- and I'd really rather be writing, reviewing, and editing documentation myself than working on building a team (I'm also not sure I was very good at the team building role). A second responsibility of the team leader is to make sure the tools and processes are in place so that community members can write documentation. I feel like Ariane (my co-leader) and I really accomplished a lot in that regard during our tenure as leaders of the team, so I felt this was a good time to step down from having final responsibility for tools and processes. A third responsibility of the team leader is to set policies and mediate disputes, and I was simply growing tired of having that responsibility.

In volunteer-driven projects like Drupal, people burn out if the work they are doing in the community is not fun or not appreciated... So, this change was basically a choice on my part to focus on the contributions I could make that are the most fun for me, and that make me feel the most appreciated. I think/hope that I've left the Documentation Team better off than it was when I started the job, and I am looking forward to this shift in my position in the Drupal community!

Jul 18 2012
Jul 18

A little over 18 months ago, Ariane K. and I started our tenure as co-leaders of the Drupal Documentation Team. We spent a lot of time working on organization, design, processes, and tools to make it easier for Drupalists to contribute to and use Drupal documentation, and I’m very proud of the many improvements we were able to make (of course, with the help of lots of other contributors!) during that time.

Ariane decided to end her co-leader term at the end of 2011, and I was planning to stay on as team leader until the end of 2012. But I’ve decided to end my term a bit earlier than I had planned, and so I am announcing today that I’m stepping down as the official Documentation Team Leader. This will allow me to concentrate on the Drupal volunteer work where I feel I’m making the most positive impact (and which, not entirely coincidentally, I enjoy the most):

  • Reviewing and committing documentation and coding standards patches to Drupal Core
  • Maintaining the API module (the module that powers api.drupal.org) and a few other contributed modules
  • Improving tools and infrastructure on Drupal.org for documentation and for programmers

Due in part to changes in the design, processes, and tools for documentation that Ariane and I helped to put in place, I think that people in the larger Drupal community are now feeling much more empowered to create and edit Drupal documentation than they were 18 months ago, and I’m not sure when the Documentation Team Leader position will be filled -- or even if we need to fill it. People in the Drupal project are currently exploring Drupal community governance, and among the questions they'll be thinking about are the leadership and structure of the Documentation Team -- so expect an announcement sometime soon.

But in the meantime, I’m sure the community as a whole will continue to write and improve Drupal documentation, and I hope that everyone who considers themselves part of the Drupal Documentation Team will continue to take pride in the great job you’re all doing every day.

Feb 01 2012
Feb 01

One of the problems that I think every open-source software project faces is how to get new contributors to the project started. It's always necessary to recruit new contributors -- not all of a project's existing contributors will stay around forever, and any project benefits from new people with fresh ideas. But it can take a lot of time from the established contributors to get new people started contributing "the right way" in an established open-source project.

We've been discussing this lately in the Drupal project, and I realized that one thing we needed was a central place to list tasks appropriate to new contributors. So I started this section today, at http://drupal.org/new-contributors.

My hope is that this section will become very useful both for new contributors and for people who are organizing sprints at DrupalCon and regional events. But to make it be a great resource, we need more tasks there. So please add tasks appropriate to new contributors (and sub-sections if appropriate): theming? translating? support? There's a template at http://drupal.org/node/1424502 to get you started. Let's make this work!

Jan 23 2012
Jan 23

For a client project last week, I needed to display automatically-generated embedded maps or links to external maps (e.g., a link to Google Maps), based on an entered address for a performance venue. In some display modes, I wanted a map on the page (such as when displaying a Venue page by itself), and in other display modes, I wanted a map link (such as when displaying venue information on a Performance page). Although this is, I'm sure, a common need on web sites, an extensive search for existing Drupal modules to didn't get me anywhere. The best solution I came up with for embedding the map involved at least three Drupal modules and several external library downloads, several of which were not yet released for Drupal 7 apart from "development" versions, and it didn't create the link to an external map that I needed.

So I thought to myself... This can't really be as difficult as using all these modules and libraries. When you go to Google Maps and map a location, Google provides code (click the Link icon near the map) for embedding that map in a web page in an iframe, and making a link to the map. I experimented a bit with the iframe and link code, and found that the latitude and longitude values could be omitted -- meaning that all you need is an address that Google maps can recognize.

This revelation allowed for a really simple solution. I used the Drupal 7 Field API to create a "Field Formatter" module that would take a plain text field containing an address that Google Maps could recognize, and instead of just displaying that text (which is what the default Text field formatter does), it would display as an embedded map, a link to Google Maps, or both. It took less than an hour to code, and works just fine for this project's purposes.

Update February 12, 2012: This module is now a full Drupal.org project, which you can download at: http://drupal.org/project/simple_gmap

Note: As with all modules on drupal.org, if you have comments or questions about this module, please search the issue queue to see if your question has already been answered, and if not, file a new issue. I'm closing comments on this post, meanwhile...

Oct 24 2011
Oct 24

I spent the last two weekends at conferences -- a lot of traveling, but it is always good to see the people I'm interacting with online every day, and meet some new people.

The weekend of October 15, I attended the Pacific Northwest Drupal Summit. Highlights:

The next weekend, I headed to the San Francisco Bay area. On Friday, I was at the Bay Area Drupal Camp Core Developer Summit. After a series of short talks (I gave one on what's happening in the Drupal documentation group), we spent the afternoon working on and discussing many aspects of Drupal. I was most excited by the novice contributors guide that Kathy H. was working on, which hopefully will be coming to Drupal.org shortly.

Saturday and Sunday I was at the Google Summer of Code (GSoC) Mentors Summit. This was a wonderful gathering of people from 175 open-source software communities where Google had sponsored students this past summer -- about 350 people who mentored students attended, and I was one of two representatives from the Drupal project. It was an "un-conference", which meant that we self-organized sessions, and most of them were discussions rather than presentations. I participated in several discussions about building better open source communities, documentation, Wikis, and Content Management Systems. My overriding feeling was that we are doing a lot of things really well in the Drupal community, but there were several ideas I heard (or particpated in creating) that could be useful for us:

  • Make the documentation "gardening" tasks (cleanups, etc.) more visible
  • Make the gardening tasks more fun.
  • To get good documentation written, have a focused sprint. The GSoC held a documentation sprint the week before the mentor summit, and the process there worked really well. They had about 4 people from each project, and went through these steps (focusing on the outcome of writing a book, rather than any other documentation tasks):
    1. Define the audience, and come up with a one-sentence summary/title for the book (fairly quick).
    2. Generate a table of contents (took 1/5 of the time).
    3. Split up, and write the chapters, not worrying about the formatting. Editing in pairs rather than individually worked really well (took 1/2 of the time).
    4. Formatting and editing, to make the different chapters share formatting. The participants felt that leaving this to the end was good, since they didn't have to worry about it while they were writing (took 3/10 of the time).
    5. Print it out (something tangible to take home). The participants felt that the ability to see the book online as well as print it out (via Lulu.com or another print-on-demand publisher) was very good for their audiences (especially less technical and academic audiences).

    They used the "Booki" tools for Python/Django, as installed at http://flossmanuals.net (which also displays the manuals they created). They all liked this system quite well. And they also said that having some "outsiders" present for the sprint was useful, to point out the things that a new person wouldn't understand.

  • Two-minute screencasts would be a good addition to documentation (with captions for hearing-impaired people, and to improve comprehension by 70% for everyone). Making screencasts would be a great Google Code-In project for students, and YouTube has a captioning tool.
  • Attracting and retaining contributors: I heard over and over the idea of thanking people for any contribution, being positive before criticizing a patch, and stressing in the community the idea of everyone being polite always.
  • Metrics: Several projects are measuring the health of their community -- here's a blog post that lists several efforts. The key is to make sure the things you measure are really reflecting the health of the community.
  • Have a "greeter" in the issue queue. If an issue waits for 3 days with no response, the current "greeter" at least says "Thanks". This duty rotates as people get tired of it.
  • Making contributing into a game could help to increase participation and retention. Book: Game storming: A playbook for innovators, rulebreakers, and changemakers, by Dave Gray, Sunni Brown, James Macanufo (O'Reilly). Key ideas from the session:
    • People get points for doing things that the project wants to encourage.
    • Focus is on encouraging new contributions and more frequent contributions.
    • Earning points gets you to a "level". Best if there is some fun pop-up or badge associated with this.
    • Make sure the points/levels are not associated with real money or benefits, just recognition.
    • Be careful about how the points are awarded. For instance, if you just count patch submissions, people will contribute lots of very small patches and be recognized more than people making larger contributions. So you could instead have peer-review ratings for issues (or "quests") to determine how many points you would get for fixing that issue, or maybe have a limit to how many patch-related points you could get in a certain time frame. Another idea: award "heart" points for the importance of the task (or the amount it is needed for the project, or for tasks people aren't doing that need to be done), and "star" points for the difficulty. Level advancement could be based on the sum of hearts and stars.
    • Be careful about gender/age/culture issues when designing the game feel, so as not to alienate potential contributors.
    • Keep the mechanics of the game simple, and automatic when you contribute.
    • The game should support knowledge gain and mastery. Peer review can help - don't award points without someone approving the contribution. If a task is worth a certain number of points, someone can decide how many to allocate to which participant.
    • Integrate the game into the project - information on the home page of the project (leader board tag cloud?), pull points from regular contributing activities (issue queue), don't change how people are already contributing but make the points a side effect of what people should be doing.
Oct 17 2011
Oct 17

We're having a Drupal API documentation cleanup sprint, to bring the function and file documentation headers up our Drupal 7 documentation standards. If you want to participate, see issue http://drupal.org/node/1310084 for instructions -- new contributors welcome!

Sep 27 2011
Sep 27

Hello from Jennifer and Ariane, your friendly Drupal Documentation Team co-leads! It’s time for a quarterly update on what’s happening in the Documentation Team—we've been working on some major restructuring of documentation and the Docs Team since our last update (June 28, 2011), and we'd like to get you up to date on our plans, and other events and news.

Docs restructuring

The big news for this quarter is that we are in the midst of some restructuring of the online Drupal documentation, as well as of the Documentation Team itself. Nothing has been completely settled yet, but here is an outline of our plans, reasoning, and links to more information and where you can get involved in the discussion.

Community documentation

The main issue we need to resolve is that the current online documentation on Drupal.org is way too overwhelming for one coordinator to manage. Having one coordinator is a single point of failure, and has led to several past Docs Team leaders getting burned out and leaving the post.

The current documentation has many features of a wiki: anyone can edit most of the pages, and anyone can add new pages... Yet we have found that potential documentation contributors are timid about actually editing and adding pages. So what we would like to do is turn responsibility over to the community as a whole, and make it abundantly clear that everyone can edit and contribute. The plans have been solidified on this issue: #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained., and if you'd like to help with the infrastructure changes (site building and module development), we are currently coordinating docs infrastructure work on http://groups.drupal.org/node/174499 . Follow-up changes to the infrastructure are being discussed on #1287784: Follow-ups to improve the community docs.

Curated documentation

Once we have those changes deployed, the next idea is to start a new section of documentation that will be more directly curated and maintained by the official Documentation Team leadership—and therefore, more limited in scope. The idea here is that careful decisions will be made about what are the "essentials" that belong in this documentation (which might be called "official documentation" or "user manual" or "curated documentation" or "essentials" or ...), and a small team will be responsible for maintaining the documentation. This idea has not been completely fleshed out yet; it's being discussed on issue #1291058: Discussion: Make a curated docs section/system if you'd like to join the discussion.

Outside documentation

Another idea that's in development is to make it possible to search external documentation—for instance, Drupal tutorials on blogs, and curriculum on Drupal company web sites. Lin Clark is currently exploring ideas for automatic collection of posts involving RDFa/microdata and SPARQL, and there will hopefully be more ideas and discussion about this in the next few months. Watch the Documentation Team on groups.drupal.org for updates!

API reference

We don't expect anything to change in the process, maintenance, or location of the API reference site on api.drupal.org. That process is actually working fine, and Jennifer is pleased to report that there have been many new contributors stepping up to submit patches lately. (Note: sprint coming up—see below!)

July - September events

Here are some events that the Documentation Team participated in during the third quarter of 2011:

  • DrupalCon London - BoF Gathering
  • At the end of August, many from the Docs Team were at DrupalCon London. We had BoFs ("Birds of a Feather" informal discussions) about DITA (a standard for documentation), the proposed new Help system for Drupal 8, and Lin Clark's ideas about using RDFa or microdata to build an index to documentation from Drupal Planet (see above).
  • At DrupalCon, there was also a Core Conversation session about DITA and the new help system.
  • DrupalCon London - Sprint

  • And of course we also had a very successful Documentation Sprint on the last day of the conference, with three tables of participants helping each other become knowledgeable documentation contributors. Thanks to all who participated!
  • We are holding weekly "Documentation Office Hours"—one-hour IRC meetings on Tuesday afternoon (North American time), open to anyone for questions and discussions about contributing to documentation. It seems like it's been very helpful to have a definite time when people can find us on IRC, and we plan to continue with this schedule for the foreseeable future.

Upcoming API docs sprint

The API documentation on api.drupal.org has been improving slowly but surely over the past couple of years (I think/hope). But there are still quite a few areas where the documentation does not conform to the API documentation standards. Unfortunately, patches that do wholesale changes to documentation headers are disruptive to the ongoing improvements of the Drupal code, since they often require that many patches be "re-rolled" so that they will apply to the new code-base. So, we've been told several times that we needed to postpone these types of large-scale updates.

However, in early November, a patch is scheduled to go into Drupal 8 that will move all of the core Drupal files into a "core" directory. This will be a huge disruption, as every patch for Drupal 8 will need to be re-rolled. Because of this, it's a great time do other disruptive work, and we plan to have an API Documentation sprint just after that patch goes in, where we'll do a defined set of wholesale improvements to the in-code docs for Drupal 8. Mark your calendar—I'm hoping that we have lots of participants (including new API docs contributors) so the work for each person will be manageable!

Process, communication, and infrastructure milestones

Aside from the infrastructure and team reorganization mentioned above, there were some smaller initiatives in the Documentation Team this quarter:

  • In July, Neil Drumm (drumm), with help from a few others, deployed a new feature to your Drupal.org user profile and Drupal.org company profile, aimed at recognizing documentation contributions: there is now a line in the History section of user profiles and the right sidebar of the new Marketplace company profile that says something like “Over 100 edits”, reflecting how many documentation page revisions you have made since joining Drupal.org. This is a small way of recognizing documentation contributions to the Drupal project.
  • At DrupalCon Chicago, Dries suggested that in Drupal 8 development, each change would have to pass through a series of "gates" in order to be accepted, and Documentation was listed as one of his "gates", but it wasn’t defined what the gates really meant. So, a conversation was started with Jennifer, Angela Byron, and other members of the community, and in July, the Documentation gate standards were adopted. The adopted gates are listed on the gates page.
  • In July, Angela Byron and Jennifer (along with many others) finalized two changes to the Drupal issue workflow: Issue Summaries and Change Notification nodes. With issue summaries, anyone can now edit the node body of any issue, to use the body as an Issue Summary, and we have a suggested issue summary template to use when filing or updating issues. With change notification nodes: for Drupal Core (and any other project that chooses to use them), after an issue is fixed, if the committed fix involves changes to the user interface or programming interface, a Change Notice node should be created to document the change. Then the Documentation Team, Coder module team, Examples module team, module developers, and theme developers can all visit http://drupal.org/list-changes (simple view) and http://drupal.org/list-change-updates (maintainer view) to find relevant changes that affect them or that need to be acted upon.
  • Jennifer mentored Google Summer of Code student Tamás Demeter-Haludka (Yorirou) over the summer, who created the Conditional Text module. We expect to use this for the new Help system and probably the curated docs as well.

Next steps

If you're interested in helping with Drupal documentation:

That's all for now—we hope that your fall (or spring, if you're in the Southern Hemisphere) goes well, and we'll be in touch!

Sep 08 2011
Sep 08

At DrupalCon London a couple of weeks ago, I was approached by several developers who wanted to do projects that would help the Drupal Documentation team. I had a few thoughts then, but now I have something more organized... If you are a Drupal site builder or a Drupal/PHP programmer, the Documentation team needs your help with the tasks listed here:
http://groups.drupal.org/node/174499

These are all tasks that I would love to do myself, if only I had time between my freelancing work and the time it takes to be a Drupal Documentation Team co-lead... So I think they're all quite doable and interesting, and I would love to mentor some new Drupal contributors in taking them on! Please comment on the groups.drupal.org page and not here, if you are interested (or find me, jhodgdon, in the #drupal-docs IRC channel). Thanks!

Aug 11 2011
Aug 11

At local Drupal group meetings I've been to lately, the big question among those of us who build sites with Drupal is (as you might guess): Is it time to switch to Drupal 7? I can't give you a simple yes or no answer to this question -- I think it depends on your situation, mainly due to the state of contributed modules and some key core bugs -- how disappointing! Drupal 7 was released on January 5 of this year -- it has been out for more than seven months -- and the D7CX (Drupal 7 Contrib Experience) pledge (which many signed and few fulfilled), and the promise to keep the core bug numbers down was supposed to mean that Drupal 7 (unlike Drupal 6) would really be usable on its release date. I'm not blaming the core developers or module maintainers for the fact that it wasn't -- we're all volunteers on the Drupal project. Fixing core bugs is not always the most exciting work, and updating a module from Drupal 6 to Drupal 7 (and providing a data migration path) is not exactly easy or automatic. But it's still a disappointment that for all of the hype about D7CX and the bug counts, more than seven months after the release of Drupal 7 I am still not convinced that it's time for everyone to switch.

So let's return to the practical question: Is it time for you to switch to Drupal 7? As I said above, I think it depends on your situation:

  • If you have a staff of programmers, and a large-budget project: Yes. If you are willing to expend enough effort, you can most certainly build a web site in Drupal 7 with whatever functionality you want, and it's a LOT better than Drupal 6 in many respects. But this case is a very small percentage of all Drupal projects.
  • If you are building a web site that doesn't need any contributed modules at all: Yes. You can almost certainly also upgrade an existing Drupal 6 site with no contributed modules to Drupal 7. But this case is also pretty rare.
  • If you have an existing Drupal 6 site with contributed modules (and a smaller budget): Probably not, although the answer to this is getting steadily closer to Yes, as module maintainers find the time (or someone funds them) to port their modules to Drupal 7 and/or build a data migration path.
  • If you are building a new site with contributed modules (and a smaller budget): Probably not. I'm sure many people would disagree with me on that answer, but having recently had the (dubious) pleasure of working on a couple of Drupal 7 website projects, I am sticking to that answer. Two problems I ran into on my recent projects will serve to illustrate:
    • Internationalization: if your site will be multi-lingual and uses Views, you will need the Internationalization Views module. However, as of this writing, it is completely unusable -- the base Internationalization module was updated recently, in a way that made Internationalization Views completely break (this will hopefully be fixed soon). And I ran into several other Internationalization issues as well, which don't have solutions on the horizon (beyond the expedient solutions I had to adopt: hack core, hack contrib, turn off validations that were causing me problems, etc.) (and I do mean hack! In the sense of ugly, rough cuts).
    • Complex queries: In several situations I'm aware of, there are some bugs in database queries that cause them to return no results. I've personally run into it when building Views with complex filters, and there is another reported core issue when using Search with content access permissions.

    If you are willing to do some programming or patching, you can probably get around these types of issues -- just don't expect everything to work well "out of the box".... Which I think was the promise/intention of the D7CX and bug count efforts?

In summary: although Core is getting better all the time, in reality you can't build most sites without using at least a few contributed modules (and most sites will want to use a custom or contributed theme, too). So maybe we need to concentrate more on the contrib ecosystem, and the impacts that changing Core have on Contrib, rather than just thinking about how to make Drupal core even more awesome, efficient, and usable. And (although everyone hates them), maybe we should consider even lower thresholds for bug counts, and count it as a critical bug if some change in Core breaks a bunch of contributed modules? Something to consider, anyway... Let's not have a multiple-month delay in Drupal 8 between its release and when I can definitely say "Yes, it's time to switch".

Apr 21 2011
Apr 21

There's a lot of energy right now in the Drupal Documentation Team, which is great! My docs team co-lead Ariane has put together a team of dedicated folks who are regularly contributing to the Drupal.org on-line documentation, and their efforts are really paying off in better documentation.

But there isn't quite so much energy in the API/programmer section of the docs team, which I'm in charge of, so I'd like to make a Call to Action. What I'd like to have on the Docs Team:

If you'd like to get started:

Any takers?

Why would you want to do this?

I find that writing API documentation is fun and rewarding -- I got recognized as one of the top 10 patch contributors to Drupal 7 due mostly to writing API documentation patches. They're mostly fairly quick and easy, and non-controversial, so when you write a documentation patch, it will probably get accepted -- unlike the struggle it is to get a code patch accepted. So you can get many instances of a small amount of glory for your valued efforts!

That said, I'd welcome suggestions on how to recruit and retain programmer-writers... What I've seen in the past couple of years is that quite a few programmers have decided they want to contribute to the Drupal project, and have started by making an API documentation improvement patch. This is of course welcome and helpful, but most of these contributors have then stopped after one or two patches, and either moved on to other contributions (core code patches, contributed modules, etc.), or given up on contributing to the project -- I'm not sure which. It takes a certain amount of time and effort to educate new contributors on code and documentation standards, how to make patches, how to find what to work on, etc. So although I am happy to do this, it would be much more efficient if some of the new contributors would stay on and keep making API documentation patches. I hope they all feel that their contributions were valued and recognized... what else can I do to help retain them?

Post your suggestions here, please!

Mar 22 2011
Mar 22

One of the tasks that delayed my recent effort to migrate completely off using the Windows operating system was that I needed a new system for tracking my time and generating invoices. I used to use a custom Microsoft Access database that I created quite a few years ago, called Poplar Solo, which is available for free download on poplarware.com (and it works fine, if you have Microsoft Access available). But obviously, if I was not going to use Windows, I needed a different solution.

Being a devoted Drupal programmer and site builder, I of course thought first of Drupal as the platform for the new solution. My first step was to research the available Drupal modules for invoicing and time tracking, and I found a few, but none exactly fit my needs (which I think are fairly standard for a freelance Drupal contractor):

  • Track both overhead and billable hours, by client and job (including some overhead hours, such as time spent on marketing and education).
  • Track certain overhead expenses that I generally don't pay out of my business checking account (miles driven for business purposes, parking, bus fare, and food items) along with hours.
  • Invoice some clients for billable hours (possibly using different billing rates for different jobs), some clients for fixed dollar amounts, and some clients for both hours and amounts.
  • Choose when to invoice and which items to include on each invoice.
  • Generate reports on hours and overhead expenses.

So, given that no Drupal module I found did exactly what I wanted, I had to build it myself. I used Drupal 6.x, CCK, Flag, Views 6.x-2.x, Views Bulk Operations, and the existing Time Tracker module I found to build an invoicing and time tracking system, which I named "PS Time and Invoice" (PS is in homage to its predecessor, Poplar Solo). Because I thought it might be useful to others, I've made it available on Drupal.org as a "sandbox" project.

Besides solving my invoicing problem, building this system was also an exercise in Views programming. So, being a Drupal documentation fanatic (I'd have to be to have taken on the job as co-lead of the Documentation group!), I took the opportunity to add copious quantities of documentation to this module. You might want to check it out if you need a model for Views field handlers, Views join handlers, Views style plugins, defining CCK fields programmatically, or Flag programming.

One other reason someone might find this module useful is that it contains a Views style plugin for a table with column sums (you can configure which columns to sum). I was trying to use the existing Views Calc module to do this, but it doesn't currently work with table grouping (which I needed for some of my reports and invoices), and it also didn't work with some of the calculated fields I defined in my module. I found it easier to define my own table-with-column-sums style plugin than to fix the Views Calc table plugin, because the way the Views Calc plugin was set up, getting it to work with my fields and grouping was not going to be easy.

So, if you want to try out this module for time tracking and invoicing, use it as an example for your module, or grab the table-with-sums style Views style plugin, you can download PS Time and Invoice on drupal.org. (And by the way, if you find problems with this module or have suggestions for improvements, I'd appreciate it if you would use the issue queue there to report them, rather than commenting here.)

Jan 04 2011
Jan 04

Drupal 7.0 is supposed to come out in a few hours, and Greg Knaddison has come out with his final 7.0 patch contributor statistics. I (jhodgdon) feel honored to be listed there as the #6 contributor of patches. Of course, there's a bit of meaninglessness in those statistics, since it's just counting the sheer number of patches, not the value of the patches -- I wrote and reviewed a lot of fairly small patches, mostly fixing the Drupal in-code documentation that is used to build the Drupal API reference site. But there are definitely a few meaty code patches buried in my statistics too, and in any case, I am proud of my contributions to improving the API reference documentation.

It's unfortunate that those statistics can't measure other important contributions to Drupal, such as writing and revising the on-line documentation, maintaining key contributed modules we all use to build Drupal sites, keeping the family of *.drupal.org sites up and running, and maintaining infrastructure modules used by Drupal contributors (API, Project et al, Coder, etc.). So I'd like to recognize those people as important contributors to Drupal 7 as well.

I also wanted to take a moment to suggest that everyone who uses Drupal consider contributing. The Contribute to Drupal section of Drupal.org lists 9 different ways that you can contribute -- as an open-source project, Drupal can use anyone's time and skills (or if those are lacking: money). As the Documentation Team co-leader, of course I think that contributing to Documentation is a great way to start out -- even if you can't write all that well in English, you can still do documentation reviews, or any number of other tasks.

I've also started on a personal resolution/campaign to review at least one Drupal patch a day in 2011, and write at least one Drupal patch a day. Both patch writing and patch reviewing are needed, which is why I decided to resolve to do both... So far, it's the 4th of January, and I've managed to keep on track for 4 days -- anyone care to join me?

May 19 2010
May 19

Most of the clients I set up Drupal web sites for are not experts at hand-editing HTML, and prefer to use a WYSIWYG (What You See Is What You Get) or Rich Text editor to create their content. I generally set them up with the WYSIWYG API module, and use the FCK Editor or CK Editor plugin. Over the couple of years I have been using this module, I've learned a few configuration tricks, so I thought I'd share them here.

Why choose the WYSIWYG API module? The main reason for choosing to use the WYSIWYG API module rather than other editor modules available to Drupal is that it's smart about where to display the rich text editor: It only displays on a text area if that text area can contain formatted text (which it can detect automatically by whether the text area has an associated Input Format field). With other editor modules, you have to go through a lengthy process of defining which text area fields on which pages should have the rich text editor enabled, but WYSIWYG takes away this headache. A secondary reason for choosing this module is that it allows you to use different editors and different editor profiles for different input formats, which is quite convenient. Installation This is fairly straightforward: install the WYSIWYG API module in the normal Drupal way, and follow the on-screen instructions on the WYSIWYG configuration page to download the desired editor plugin to the correct directory on your web server. Basic Configuration After installing the editor plugins you want to use, you have to define WYSIWYG editor profiles for each of the input formats on your system that need to have rich text editors. To do this:
  • Visit the Input Formats configuration page, and set up your input formats (choose which HTML tags should be usable in which input formats, and who should be able to use which input formats).
  • Visit the WYSIWYG configuration page.
  • Choose the FCK editor as the editor of choice for each input format that needs rich text editing, and save the configuration.
  • Click "Edit" next to each input format that is using an editor, to configure the edtior profile.
  • On the configuration screen, choose the buttons you want to use and set up other desired parameters. For instance, you might consider just enabling the "Paste Text" button rather than the other paste buttons, because people often end up with garbage in their HTML if they paste in rich text. Also, you should probably just turn on the buttons that correspond to allowed HTML tags for each input format.
  • Save the configuration.
Skins The CK Editor plugin has a concept of editor "skins", which add styling to the editor. If you have a client that cares about such things, you can force the CK Editor within the WYSIWYG module to use the skin you want by deleting the other skin directories within the sites/all/libraries/ckeditor/skins directory. Otherwise, you're likely to get a somewhat random skin chosen. Random-placement images Sometimes clients want to be able to insert images directly into the body of their content (like the way WordPress lets you insert images), rather than having a structured page template (where you would define ahead of time where images should appear and have separate fields for uploading them). This can be accomplished by using the IMCE module, along with the IMCE WYSIWYG Bridge module. To set it up:
  • Install and enable both additional modules in the normal Drupal way.
  • Visit the IMCE configuration page. Set up at least one IMCE profile, and assign your profile(s) to the user roles that you want to be able to use IMCE.
  • Visit the WYSIWYG configuration page. For each input format that allows image tags, click the "edit" link to configure the editor profile.
  • Enable the IMCE plugin and the Image button, in the Buttons and Plugins section.
  • Save your configuration.

Now, when you are editing, you can click the Image button, which pops up an image dialog box. From there you can click the "Browse server" button to find an uploaded image, and then click "Upload" to upload new images to the server directory you configured in your IMCE profile. After selecting the image you want, click "Send to FCK Editor" to return to the image dialog box. You can then align the image, define the size, etc. The process is a bit counter-intuitive, but you (and your clients or other users you train) will get used to it fairly quickly.

Flash The IMCE module also allows you to embed Flash files directly in the editor. To configure this, you need to follow the steps above to configure IMCE for images, with these additional steps:
  • When you are on the IMCE profile configuration page, add "swf" as an allowed file extension.
  • When you are on the WYSIWYG profile configuration page, enable the "Flash" button.

Inserting Flash files then works the same way as inserting images, except you start by clicking the Flash button.

That's all I can think of at the moment -- hope you find this helpful!

Apr 27 2010
Apr 27

The Seattle Drupal User Group put on a free Drupal workshop for beginners in October of 2009, called the "Seattle Drupal Clinic". I now have a web site up at poplarclass.com that contains the agenda, curriculum, planning spreadsheets, a "lessons learned" page, and other resources. If your group is planning a similar workshop, you might find it useful, and all of the information there has been placed in the public domain.

We're also planning to have a second workshop this year, with an updated curriculum, so be sure to check back on the site to see what's up.

Apr 23 2010
Apr 23

I just got back from DrupalCon San Francisco, which was a blast! I went to only two formal sessions, presented 1 "BOF" (informal) session, was a panelist for two panel sessions, and spent the rest of the time coding, reviewing patches, and meeting all the folks I already knew on-line from my work on the Drupal open-source project.

Highlights:

photo of panel discussion
  • Being recognized at the first keynote address as being currently the #7 contributor of software patches (by number, not quality/importance) to the in-development version 7 of Drupal.
  • Meeting the other top contributors to Drupal in person, finally!
  • Getting Doug Green officially back on as co-maintainer of the core Search module -- being the sole maintainer of a neglected part of Drupal core is a lonely job.
  • Showing people how easy it is to create a Drupal patch at my early morning BOF on Wednesday, and having 20 people or so show up at that hour to learn about it.
  • Mentoring several new (and hopefully continuing) contributors to Drupal at code sprints and in the "Coder Lounge".
  • Programming until midnight in the Coder Lounge, and then seeing all the progress others had continued to make in the wee hours of the morning when I got up.
  • Seeing 4 or 5 rooms jammed full of people contributing to Drupal at the post-conference sprint.
  • Having Andy Laken come up to me the day after our panel on freelancing with Drupal and tell me it inspired him to keep going and get his business in order (he took the photo above)

I'm now looking forward to the DrupalCon Chicago in March of 2011, and maybe DrupalCon Copenhagen this August! Thanks to all the organizers!!

Mar 16 2010
Mar 16

I recently agreed to take on two new roles in the Drupal open-source project: maintainer of the core Search module, and documentation volunteer coordinator, specifically for the in-code API documentation that's displayed on api.drupal.org. I'm excited to be part of helping Drupal 7 come together, but to make it really successful, we need your help to get Drupal 7 documented! We need to get the API and Module Update Guide documentation fixed up, so that module developers can make their modules available for Drupal 7, and we need to get the Handbook updated for Drupal 7 so that less expert users can figure out how to use it.

Pretty much anyone can help in this effort. To get you started, we have a page listing what needs to be done, and both Ariane (arianek) and I (jhodgdon) are often available on IRC (#drupal-docs or #drupal-contribute). So feel free to jump in at any time!

Also, if you're headed for DrupalCon San Francisco in April, please consider coming for the Sunday or Thursday sprint days. We will have documentation sprints going on, and people available to get you started, point you to tasks, etc.

Thanks!

Dec 08 2009
Dec 08

I recently completed the process of adding SimpleTest tests to two modules that I maintain on drupal.org: Porter Stemmer (a module that adds linguistics-based matching of word forms to Drupal's core Search module, so that you can match "walk", "walking", "walks" etc. in searches), and Search by Page (a module that lets you search Drupal site pages (nodes, user profiles, attachments, and other pages such as views) as they are rendered by your theme, and allows you to restrict searching to certain content types, user roles, attachment fields, and/or other pages on your site).

It was an interesting experience. SimpleTest is pretty well documented, and I've been a professional software developer for a long time, so the concept of testing is not new to me. But it took quite a while to decide exactly what I should test (functional and unit tests), to figure out the details of SimpleTest (such as how to get cron to run and how to use its built-in browser), and when my first tries at tests inevitably failed, to decide whether the tests or the modules were at fault and fix the bugs.

The end result was worth it though. For one thing, I found several bugs both modules in the course of testing, as the tests are quite thorough. For instance, the Porter Stemmer tests go through a huge list of words provided by Porter (the creator of the stemming algorithm) and verifies that all the words are stemmed correctly to their root forms, and also has a functional test that verifies that the module meshes correctly with Drupal's core Search module. The Search by Page module tests that only the content you want to search is searched, that permissions are honored, and also tests many more options than an ad-hoc "let's see if this is working" sort of test would be able to verify.

Another benefit is "regression testing": whenever I make an update to either module, I can run the tests and be reasonably certain that my changes aren't going to break anything. And since SimpleTest has been incorporated into the core of Drupal version 7, when I port my modules to Drupal 7, I can also port the tests and once I get the tests to pass, I'll be reasonably certain that my modules are working.

All you other module maintainers out there: I recommend that you learn about SimpleTest as soon as possible, if you haven't done so already!

Aug 04 2009
Aug 04

A few weeks ago, I became the co-maintainer of the Porter Stemmer module for Drupal, which adds American English stemming to Drupal's core search functionality. (Stemming is the process of reducing words to their stems for better searching, so that for instance walk, walking, walks, and walked will all be equivalent in a search.)

Today I released a new version (6.x-2.0) of Porter Stemmer, which updates the module to use Version 2 of Porter's stemming algorithm (the version Porter currently recommends using for production applications). I also was able to completely test the stemming functionality of the module using the SimpleTest framework, and verify that every word in Porter's word list is stemmed correctly by the module.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web