Blog

Drupal development, project updates, occasional knee / head slappers

Sep 13, 2011

Want to learn Drupal 7 development, but haven't had the time yet? Have a development team that needs to get on board with Drupal 7 fast? Are you teaching Drupal and need training material for your students?

Build a Module.com V.2 has been officially released, complete with over 12 hours and 130 new Drupal 7 development video tutorials. The training takes you all the way from building your first Drupal 7 module to really digging deep into the new Database API, the menu system, building forms, and there's even nearly 2 hours dedicated to getting up to speed with jQuery and JavaScript in Drupal 7.

The Build a Module.com site has been entirely revamped to include a super-clean interface for watching and browsing videos, new video organization, and a community forum for subscriber-to-subscriber support.

Tons of free Drupal development training material

There's over 5 hours of free videos available so you can learn a ton without having to purchase anything, though subscriptions, HD downloads as well as DVDs are available for full access to the videos. Once a purchase has been made, the entire source code for the examples used in the videos will be available for download so you can easily follow along.

Here's a sample of the free videos:

Introduction to Module Building

Coding standards, the Form API and the menu system:

Theming and the Database API

Working with users and nodes

Working with jQuery and JavaScript in Drupal 7

A few extras for newsletter subscribers

Signing up for the newsletter also gets you access to a number of other free videos, including:

Adding usability with the #state attribute
Learn how to build awesomely usable forms using the #state attribute to show and hide elements on demand.

Modifying forms with hook_form_alter()
Ever wanted to change a Drupal form, but didn't know how? Look no further, here's how.

Adding autocomplete to a text input
Take a look behind the magic of autocomplete inputs - awesome for search boxes, usernames and more.

Using the #ajax attribute for dynamic form building
How to build forms dynamically - add checkboxes, remove textareas, load new fieldsets, you name it. And all without a page reload. Slick!

How to use render arrays and tabs
I bet you're at least a bit curious about render arrays. They're a big deal, like you! Learn how to use them to allow your pages to be modified by other modules.

How to use sub-tabs
Tabs are nice, but what about tabs of tabs? Well, here you go.

How to load JavaScript after a page is done loading
Ever wanted to add Javascript and CSS on the fly, Ajax-style? It's super easy with Drupal 7, check it out.

Questions?

If you have any questions or have any material you'd like to see covered, please drop me a line.

Nov 7, 2010

On this page

  1. Summary
  2. Why this guide exists
  3. Exportability and singleness of purpose
  4. Microphone adaptors
  5. iPhone / iPod Touch microphones
  6. Bluetooth interfaces
  7. Studio shells
  8. Tripods and stabilizers
  9. MIDI inputs
  10. 1/8in guitar input (i.e. GuitarJack)
  11. Discussions about input devices
  12. Want a feature in an app? Ask for it!
  13. Multitrack recording apps
  14. Studio and sequencer apps
  15. Looping apps
  16. Learning apps
  17. Single instrument apps
  18. See also

Summary

There are some decent tools for music recording, editing and mastering on the iPhone or iPod Touch, but whether you'll really want to commit to learning the tools and using the specific hardware for the job depends on your ultimate goals. If you want to be able to get working almost instantaneously, the limitations of music tools and instruments inspire creativity in you almost as much as the features, and you value ultra-portability, it might be worth it to explore the iPhone as a real tool. If you want to push the boundaries of what a little touch screen can accomplish musically, you'll also probably have a satisfying experience.

Conversely, if you're looking for an experience and tool set like you'd get with Logic, Ableton Live, Nuendo or Reason, you will soon find yourself frustrated and out hours of research and ramp-up time. If the lack of fade in and out envelopes on tracks in a DAW is a deal breaker for you, then maybe I can save you a bit of heartache and suggest you invest the time in the tools you already like using.

That said, the future is bright. Already, Apple dropped restrictions for third-party support of hardware, meaning that hardware and software can have two different providers. Bluetooth keyboards are now compatible, meaning that DIY pedal banks for hands-free recording and looping can become a reality. There are already a couple of 25-key keyboards available. There are MIDI and direct-line guitar / bass inputs. There are some nice microphones, and ways to use other mics as well. It will take a bit of time for all the software to built support for these hardware tools - for example, I don't think any of the below mentioned apps support keyboard operations - but many of them are talking about it already.

The wide adoption of the iPad is helping drive development for richer iPad apps, and some of that work is getting pushed back to the iPhone and iPod Touch versions. Apps are being actively developed, and the narrowness of focus of some of these apps means that many of them are more polished than their desktop counterparts (if there even are desktop counterparts). Whenever I bumped into something I wanted from an app, a search through the developers forums revealed that other people wanted it to, and the developer had mentioned that it was something they were planning on including in the next version. Most of the popular apps support methods of copying and pasting audio between apps, making it possible to use one app for rhythm, one for guitar emulation and another for vocals, and mix them all together in yet another app.

If you're looking for a robust recording / editing / mastering environment from the iPhone or iPod Touch, you might be disappointed now, but you might very well find one in the next several months.

Why this guide exists

On my list of priorities, right under being a kick-ass father and husband and mastering the craft of my livelihood, is becoming a competent musician. But because the other priorities along with feeding myself, exercising and a maintaining a minimum of personal hygiene take up the vast majority of my waking hours, there's precious little left to spend on the lesser priorities, even if they're only fourth on the list.

Over the years, I've boiled down my music workstations to a fairly simple set of tools that facilitate relatively rapid set-up. Sometimes that workstation is my Martin acoustic guitar and a notebook, and other times it's a couple of MIDI keyboards and a laptop running Ableton Live and Reason. But, however humble these setups might be, they still require a particular environment (i.e. no one else is around) and in the case of my electronic setup, it takes a 5 to 15 minutes to boot everything up and figure out what I want to work on. It's enough that I can count how many times I've actually sat down and worked on something over the last three years on two hands. At that pace, I'm not going to hit the 10,000 hour mark required for mastery until well into my next life.

So, I began exploring my other options and discovered that with $50 or so of software, I could turn my iPod Touch (generation 4) into a respectable pocketable studio as well as leverage it as a rapid learning tool. And, since I made a permanent space in my pocket for an earbud case, all I need is one free hand to compose a melody, to learn how a tune I want to learn is put together, or lay down a sick beat, and I can do it anywhere. The other night I played with looping while on walk. One night I goofed around with a little electronic piece while laying in bed. Basically, I've found a way to take advantage of the small spaces between my other tackling my bigger priorities and leverage them to make some headway in musicianship.

It took a while to figure out what was out there in terms of hardware and software as well as what the current limitations are. So, I combined my personal experiences and research along with some great reviews and guides out there into a single document that should help other people seeking a pocketable mobile studio get started with a lot less time and effort than it took me.

If you find this guide helpful, I would be grateful if you'd post back about your experiences and anything that you learned along the way.

Exportability and singleness of purpose

One thing I had to get used to right off the bat is that most apps do one thing and do it well, and the trick to getting them all working together is support of audio copy and paste. So, where you might use Nano Studio to create a nice synth track, and Beatmaker for the beat, you will be copying the audio from those apps into a multitrack app like Multitrack DAW or Fourtrack to stitch everything together. Luckily, many of the best apps out there support this kind of copy and paste, and many of those that don't have it planned for the next version.

Because you'll be hopping from one app to another, using an iPod Touch or iPhone that supports multitasking adds some additional speed to the process.

Microphone adaptors

My first thought was that it would be perfect to have the right set of adaptors to use any mic with the iPod Touch. I have a cheapy lapel mic with a 3.5mm plug and a Shure 58 with an XLR plug, and would rather be able to use these than have to buy a dedicated iPhone mic. I bought a number of components off of Amazon, some of which worked, some of which didn't.

The first thing I needed was a microphone / headset splitter so that I could monitor the audio while recording. I bought one called the Headset Buddy ($14.65):

Headset Buddy

There's another, sexier-looking adapter with a right-angle plug here ($24.50), which I did not buy:

Headphone and microphone splitter

The Headset Buddy worked to connect my dinky Cyber Acoustics ACM-1 lapel mic ($1.48 + $5.99 shipping):

CA Microphone

As well as my Plantronics .Audio 645 headset ($27.96, which happens to have really good sound, better than about 5 other headsets I tried):

Plantronics headset

When I tried it with an Olympus ME52W ($15.89), which I bought to use to use my iPod Touch as a wireless mic when I give talks, it didn't work. There was no sound:

Olympus mic

When I talked to Olympus support, they suggested that maybe the problem was that the microphone was mono. You can tell it's mono because of the single stripe on the plug, and if you look at the other two mics above that did work, they have two stripes indicating they're stereo, so that might be the issue.

Next I bought a 3.5mm to XLR adapter ($8.50) to try to hook my Shure 58:

XLR to 3.5mm jack

Unfortunately, when I plugged this into the Headset Buddy this also produced no sound. The 3.5mm end is stereo, which maybe conflicts with the theory that the mic has to be stereo to work. However, it's also possible that the power the Shure 58 pulls is too much or too little and doesn't trigger the right response in the iPod Touch.

One suggestion I read about was to use a special iPhone to XLR / headphone adaptor ($23.50), so instead of using a separate mic / headphone splitter, you'd plug this guy directly in:

3.5mm to XLR and headphone jack

iPhone / iPod Touch microphones

Extenders

I haven't gotten to try any specifically iPhone / iPod Touch mics besides the built-in mic for the iPod touch G4 (which so far really bites the big one, especially with the terrible interference when wifi is on) and the ones on both the Apple earphones with mic ($29.00) and Apple in-ear headphones with mic ($79.99), both of which appear to have the same quality mic:

Apple earbuds

In-ear Apple earbuds

Extenders

However, after readying a dizzying number of reviews, there are a few that seem to rise above the fold. These mics plug into the connector jack, and some of them do so in a way that covers up the headphone jack, so if you use an iPod Touch rather than iPhone, you need a dock extender like the iExtend ($19.97) (now discontinued, but the Dock Extender product below is still available):

iExtend

or Dock Extender ($28.95):

Dock Extender

Blue Mikey

The microphone that seems to get the most play is the [Blue Mikey] ($79.99), with the 2.0 version coming out in late October 2010:

Blue Mikey

I'm really excited to give this one a go, but can't quite justify the cost yet. Reviewers say it has great sound, and Blue is a brand that I've run into when researching respectable podcasting mics.

Belkin TuneTalk

The Belkin TuneTalk ($49.18) is a stereo microphone recorder that includes a 3.5mm microphone jack and a USB power plug (important for supplying power during longer sessions). The folks at Harmonicdog (makers of Multitrack DAW) thought the included mics had too small of a signal to be practical for studio recording. You would also need a dock extender to use headphones:

Belkin TuneTalk

Griffin iTalk Pro

The Griffin iTalk Pro ($79.95) also supplies a 3.5mm microphone jack, but has an on-board microphone and speakers (speakers could be fun for live performances using the Guitar app).

Griffin iTalk

Bluetooth interfaces

The iPhone OS 4 supports Bluetooth keyboards, but as far as I can tell, none of the apps below support keyboard controls. If I'm allowed to dream, I would imagine a keyboard with a rotating connector doc that allows you to work with the iPod Touch or iPhone in landscape or portrait mode. Also, one thing I'd really like is the ability to trigger loops hands-free with pedals, and a Bluetooth interface would be awesome for this. I built one faux-pedal bank from a wireless keyboard once (inspired by this DIY example), and it was workable, though a little clumsy. There's a nice tutorial on creating a real foot pedal bank that uses the keyboard schema here. So, as long as keyboard triggers are supported by an app, there would be some way to get foot pedals involved. So, we're waiting on apps to support Bluetooth.

To really keep this aspect of the gear pocketable, you could use a virtual laser keyboard ($149.99) or a flexible waterproof pocket keyboard ($14.95).

Bluetooth could also be used for external piano keyboards as well.

Studio shells

There are a couple of 'shells' out that add a number of microphones, controls and input jacks as a case around your iPhone / iPod touch. I also haven't gotten to try these out yet. They run a little on the spendy side, and also add some overhead to my goals of rapid execution and portability. They're small, but they won't fit in my pocket.

Belkin GoStudio

First off, the Belkin GoStudio ($98.96) adds two mics, 2 combo XLR / 1/4in jacks, a 3.5mm mic jack and controls for gain and volume. The reviews aren't so great and it apparently sucks a lot of power, but it sure looks cool:

Belkin GoStudio

Alesis ProTrack

The __Alesis ProTrack ($172) looks even cooler, and appears to add the same functionality as the GoStudio, along with phantom power for condenser mics:

Alesis ProTrack

Tripods and stabilizers

Gorilla Mobile tripod

I saw a few examples of ways to hold the iPod Touch when performing, though I haven't tried them myself. The first is the Gorilla Mobile tripod ($25.30), which sucks to the iPhone or iPod Touch with a suction cup. Alternately, you can use adhesive-backed adaptors to attach to a protective shell:

Gorilla Mobile

Car mount

You can also flip the suction cup idea and use a car mount ($12.29) to suction to a table top (for an example, see this video demoing the Everyday Looper app around 6:40:

iPhone car mount

Multi-iPhone stand

The photo below shows another neat setup, but I don't know what exactly is being used. You see three iPhones clipped onto a metal bar. The video for this, demoing Beatmaker and Guitar is pretty slick.

iPhone Stand

MIDI inputs

Right now, it looks like MIDI is on the verge of becoming real for the iPhone and iPod touch. There are a couple of devices, but since they're not supported by the apps mentioned below, they're not really useful yet for pocket studio.

MIDI Mobilizer

The MIDI Mobilizer ($69.99) allows you to capture and backup MIDI data with their MIDI Memo app, but it seems like this device wouldn't be practical for music creation until other app developers integrate with their SDK.

MIDI Mobile

Akai Synthstation25

The Akai SYNTHSTATION25 ($99) is, as far as I can tell, the first MIDI keyboard controller for the iPhone. Since it's new it looks like only the Akai SynthStation app is supported, but hopefully other apps will add support over time. I would prefer to use the MIDI Mobilizer so I could use any MIDI input, but this seems like a good second choice if apps chose to support it.

Akai SynthStation 25

iConnect MIDI

The iConnect MIDI is due to come out in January, 2011, and it looks like it might offer an interface similar to the MIDI mobilizer, with a way to route from a MIDI device through an iPhone app. The pic below shows an example of it being used with the iPad, but it will also interface with the iPhone and iPod Touch. See some clarification from the creators below.

iConnect MIDI

1/8in guitar input (i.e. GuitarJack)

The GuitarJack ($199) adapter, which comes from the folks at Sonoma, makers of FourTrack, adds a 1/4in input for a direct guitar in, 1/8in stereo mic input, and a 1/4 headphone jack. Pretty spendy, but slick:

Guitar Jack

Discussions about input devices

Much of what I learned about the above devices came from a few sources. I found that the forums for music recording apps usually have some good information, including:

Want a feature in an app? Ask for it!

Before I leap into the different apps I've tried out, I wanted to say that a lot of the developers of these apps are very responsive to support and feature requests, so I've included links to forums below each of the app descriptions. Also, you can search the forums for keywords around the features you'd like to see if they're already in the works.

Multitrack recording apps

There seem to be two leading multitrack recording apps, FourTrack ($9.99) and Multitrack DAW ($9.99). Both support audio copy / paste.

Multitrack DAW

So far, I like Multitrack DAW better for a few reasons:

  1. You can view the tracks as horizontal sound waves
  2. You can edit the tracks with precision using cut and paste
  3. You can have up to 24 tracks

Multitrack DAW

The interface is very simple, and there's not a lot to it.

Click here for the forums on Multitrack DAW

FourTrack

Fourtrack was one of the first apps I've bought, and I still have yet to use it for much. The interface is beautiful, polished and straightforward. It also has some nice effect controllers. But, the 4-track limitation, as well as the lack of a method of editing a wave once it's recorded, makes Multitrack DAW appear far superior.

Fourtrack

Click here for the FourTrack forums

Studio and sequencer apps

NanoStudio

One of my favorite music apps so far is NanoStudio ($14.99). It includes a real, flexible synthesizer with 80 or so presets and a drum kit for instruments. It then allows you to record and arrange parts in a sequencer. It includes advanced features like editing or automating the velocity, pan and various controls for each track in the sequencer. You only get 6 tracks (4 synth and 2 drum pad), but apparently you can switch presets partway through a track so you can get a lot more out than meets the eye. The presets are a lot of fun, and the number of controls to work with allow you to make unique sounds.

Nano studio

Click here for the NanoStudio forums

Beatmaker

Beatmaker ($9.99) is basically a really nice, flexible drum pad and sequencer. I haven't gotten to play with it much, but the interface is nice, the sounds are solid, and some of the features seem like they could be a lot of fun in live performances, like the ability to reverse or mute pads. Beatmaker supports audio export so you can lay down a rhythm track and load it into one of the multitrack recording apps.

Beatmaker

Click here for the Beatmaker forums.

Music Studio

I haven't gotten a chance to play with Music Studio ($14.99) much, but it looks promising. It has the same kind of feel as NanoStudio, but uses samples of real instruments and probably because of this is able to allow 128 simultaneous tracks. The keyboard controller is also really flexible (stretch and slide), and it just seems to have a nice interface all around.

Music Studio

Click here for the Music Studio forums.

Looping apps

I've found looping to be the key to really enjoying a few minutes of music making. You can use your voice or stuff around you to lay down some repeating tracks to riff off. For my laptop, I love Ableton Live, and would really like to see something similar for the iPod Touch / iPhone. There's a couple apps that come close.

Loopy

One of my favorite finds ever is Loopy ($4.99), and I prefer this to the Everyday Looper only because it allows you to have variable-length tracks. So, one track can be 4 measures, and the next can be 1 or 16. Having this ability is really critical for me to not feel overly constrained (though I have still had fun within that constraint) by the tool. I think the interface is kind of genius, though it can be tricky to work with at times. It's also beautiful and has Imogeen Heap's approval.

Loopy

Click here for the Loopy forums.

Everyday Looper

Everyday Looper ($5.99) has one of the starkest interfaces I've seen for the iPhone. It's also very easy to use, and has intuitive controls. Because all the loops have to be the same length, it's a little harder for me to use as a scratchpad, but it's still very cool, and has some great demos on Youtube.

Everyday Looper

Click here for the Everyday Looper forums

Learning apps

TabToolkit

As I started exhuastively researching apps, I finally decided to download TabToolkit ($9.99), an app that really surprised me. What it does is take various versions of tabulature (like basic guitar tabs on speed) and displays the musical notation, the tabs (i.e. where you put your fingers), and then highlights the spots on a guitar fretboard. Then, you can play the thing, and it will play it for you. You can stop at any time and scroll back or forwards as you learn. Some of the formats also include other instruments like vocals, drums and piano, so you can pretty much take apart a complex song, piece by piece, and learn what goes into it.

It also allows you to download tabs from within the app and add them to your library. A few places that have good tabs:

Tab Toolkit

There are no forums for Tab Toolkit, but they do have a blog.

Guitar

Another app that has been great so far for learning has been Guitar ($3.99). Guitar is a virtual guitar that you can strum, and it feels surprisingly natural. You can set two rows of buttons to any chord you'd like, as well as custom tune the guitar and build custom chords. You can also set a button to display a scale, or a plain fretboard. I've played with it for maybe 3 or 4 hours and have really been enjoying it. Particularly I like the idea of being able to practice or perform a tune with my iPod Touch. You can also record music and audio copy / paste it into a multitrack app.

The learning comes in when you can load other songs, view notes on the fretboard, and explore chords.

Guitar

Click here for the Guitar forums.

Single instrument apps

There are a couple of single instrument apps (including Guitar mentioned above) that I think deserve note.

I Am T-Pain

Besides having a lot of fun attempting to sing songs I've never heard before about strippers and donk with friends, the __I Am T-Pain ($2.99) app gives you Autotune, a plugin that costs $199, for 3 bucks! Admittedly, it's a little tricker to use and more limited, but if you use one of the headphone / microphone splitters mentioned above, you can route your headphone as a line-in to your computer, and then sing into the microphone to get an auto-tuned recording, in almost any scale you'd like. Basically, you use your iPhone as an effects device.

I Am T-Pain

Click here for the I Am T-Pain forums.

Gyrosynth

I've always been a sucker for old school electronic instruments, and I never really thought I'd get a pocketable theremin, but Gyrosynth ($.99) is just that. So far, it's just kind of fun to play with, but once they add some audio copy / paste and backing audio, you could use it as a real instrument in a DAW.

GyroSynth

Click here for the Gyrosynth forums.

See also

External resources

Sep 30, 2010

It took me two years, but galdarnit, I did it. I migrated a project over to Git and got to see what I've been missing this whole time. And it made me feel like a moron for waiting so long. If you're a late majority holdout like me, there's probably not much I can do to convince you to move over that hasn't been tried already. But when you get there, you can put me on the list of people that said "I told you so".

Alternately, if you're reading this because you were one of the people that told me so, and don't know about it already, you can help the Drupal Git migration team by teaching your fellow Drupalists in meetups and camps. I'm behind you all the way, though it will probably take a couple more years for me to start teaching it myself (late majority).

A lot has been written about the benefits of using Git, but there were some things I didn't run across until I started using it myself. Below is a little list to compare my Git experience with SVN:

  • Messages are way more helpful. Misspelled 'status' and it said 'Did you mean status?'. 'git status' gives you suggestions on what to do to add new files in and such.
  • Patch syntax makes more sense. "git apply" instead of "patch -p0"
  • Multi-line commit messages in a default text editor.
  • Colorful messages (I'm a sucker)
  • gitk command is really cool - Shows a graphical representation of commits over time, the interaction fo branches, nicely browsable.
  • Active IRC channel (600 people)
  • In a conflict, no files get created. There's just conflict messages in the file. You resolve and commit. SVN produces several files which can be confusing. Also don't need to mark resolved.
  • Commits contain real name and e-mail address, instead of just a username
  • Nicer progress reports when pushing - shows you percentage completed.
  • Much simpler to change remote repository hosting providers without losing data.

And here's a few resources I used to get started:

Enjoy!

Sep 29, 2010

I really get a kick out of awkward advertising. Like, maybe some focus group somewhere told them it was a good idea, but it doesn't come across quite right.

Do they really think I'm going to carry this around? Do people have a hard time throwing away plastic cards like they do magnets? Are they just messing with my head?

Sep 29, 2010

Rocking the docs with rainbows

This post is intended as one repository for the lessons learned over two solid months of documentation writing, and the other is BeauityMyDocs.com, which I put together as a free service to other doc writers to instantly add usability and consistency to docs. You paste a doc in, churn it through, and it comes out the other side with sweet features like clickable, linkable headers, a table of contents, a "see also" section, unified header levels and more. It's also just kind of fun to use (i.e. there's rainbows and stars). To see samples, all of the docs for Open Atrium and Managing News have been run through the Beautifier.

Docs are the new code

The last two months I spent writing docs for Open Atrium and Managing News was part of a project sponsored by a client who needed better docs for their organization, but who also recognized the value of contributing this effort back to the community. It was amazing opportunity to become intimately familiar with two bleeding edge projects and to work closely with the Development Seed folks who both live on and sharpen that edge.

This sponsorship came as a bit of a surprise to me. Apparently there is so much power behind Drupal, her contributed modules and distributions that the scarcity of clear, usable, or just plain existing documentation is a genuine bottleneck that is getting some attention and funding. Just a couple days ago someone posted a docs job sponsored by the Knight Foundation, and I'm wondering if these are signs of a trend.

The challenges

If Drupal is a blank piece of paper, a Development Seed distribution is an origami Voltron, and there was a long ways to go before I understood the subtleties of all the folds and creases. As webchick pointed out recently, writing docs is a practice best executed as you're learning, while experiences are fresh, and since I didn't have a lot of experience with either platform, this made for a perfect doc-writing environment.

The two projects posed some interesting challenges:

  1. While I had a blank slate for Managing News, there were existing Open Atrium docs. So how do you make a full documentation project consistent when you have existing docs that run the gambit in quality and technique?
  2. Next, while the docs for Open Atrium are on an Open Atrium site where Markdown is the norm, they would eventually get pushed to Drupal.org where docs are written in HTML. That begs the question of how to switch rapidly between working in Markdown and HTML.
  3. On both projects, we wanted docs to include a table of contents an a "see also" section with links to outside resources. I found that building these was a time-consuming and error prone process, so how do you add these nice chunks of usability without sacrificing your sanity?

For answers to these questions and more, read on Macduff!

Starting with expert outlines

One of the old-timers at Development Seed and all-around nice fellow Ian Ward started me off with outlines, and this established scaffolding around areas where the creators identified important features or potential problem areas. It was years of experience summarized in a short hierarchical list. This left me - the relative noob - free to fill it in with fresh experience without worrying about spending unnecessary time documenting less significant areas.

As I learned more about the projects, this outline went through several iterations. In the end, both projects ended up with a basic structure similar to this:

  • How to use this documentation - The parent page, containing short descriptions of each of the sections, rich with links to sub-pages.
  • Getting started - A section containing a guide for folks just installing or thinking about installing the product.
    • What is [insert product here]? - A general description of what the product does.
    • Quickstart guide - Takes the user on a guided tour of the first few steps of working with the product.
    • Case studies - Examples of how the product is or can be used in the wild.
  • Installation and upgrading - Includes sections on installing, upgrading and troubleshooting.
  • Content and configuration - A section includes anything that can be done via configuration (i.e. no code).
  • Customization and development - Modifying or extending in ways that involve code.
  • How to contribute - Ways to contribute code, translations or documentation.
  • Support - How to find or ask for support.
    •  FAQs - On one of the sites, we split this up into several areas. For example, FAQs for configuration and FAQs for development.
    •  Glossary - Odd terms that are either Drupal- or product-centric.
  • Appendix - Anything that's not active documentation.
    • Archive - Documents that are still applicable to older version of the product.
    • Marked for deletion - Docs that shouldn't be docs, or that get absorbed into other docs are moved here with a short explanation as to why the doc should be removed.

The screenshotgun

Sometimes what make a good doc a really good doc are useful screenshots. The added pizazz and usability of screenshots comes at a cost, though. Whenever a product updates it's look and feel, the screenshots are instantly out of date. And depending on how you do screenshots, they can take a lot of time.

I opted for more screenshots rather than less because a visual representation of a step is quicker to process than text, and getting up to speed as fast as possible is important. It also has the added bonus of giving users who are just browsing a more realistic walkthrough of a process.

In order to rapidly create screenshots, I used a combination of Skitch, Evernote and the Mac-based screengrabber tool. When I was writing a doc, I would compose it in Evernote for two reasons: 1) it saves as you go, and 2) you can paste images or even image data straight into your composition. So, when a doc is done in Evernote, it looks pretty close to what it will look like when posted on the final site, and you can't get that effect composing in Drupal without some WYSIWIG help. When I was ready to create a screenshot, I would do the following (these are Mac-centric instructions, but the ideas should be portable):

  1. Navigate to the page I wanted a screenshot of.
  2. Use the key combination CMD+CTRL+SHIFT+3 (tricky to do with one hand) to launch the partial-screen grabber.
  3. Click and drag a box around the area to capture and let go.
  4. The image data is now in the clipboard. If the screenshot is good as is, I go to my doc in Evernote and paste it in. If it needs some annotations, I paste it into Skitch.
  5. In Skitch, I make my annotations in red. If I need to reference something in the text, I use numbers instead of text to make it translatable (thanks for that suggestion, Ian).
  6. When I'm done, I copy the image to the clipboard (just click CTL+C while in Skitch to copy the whole thing), and then paste it into Evernote.

When I'm done write a doc and am ready to import it to a Drupal page, I do the following:

  1. I select the note in Evernote, and go to File > Export to export all of the images into a single folder.
  2. I then open the folder and rename the images to give them useful descriptions (optional, but helpful)
  3. I create a new page in the Drupal site, and upload the images via the Upload module.
  4. When a file is uploaded, it displays the URL to the image. I select this URL, paste it into the Evernote document to replace the image and surround it with the Markdown or HTML image tag.
  5. When I'm done, I paste the whole document over to the new Drupal page and preview it to make sure it's squared. Then I submit it for real.

Bonus: To capture full screens that go beyond my 1280 x 960 display, I use Paparazzi! If you're accessing a page where you need to be logged in, you need to use the "Capture from Safari" option and log in via Safari. To capture a screen where I want to get some mouse motion (and so you can't use the mouse to drag a box), I use CTRL+CMD+SHIFT+3 (also tough with one hand) to grab the full screen, paste it in Sktich and drag the borders to crop it. The screenshot guidelines in the Open Atrium docs may also be useful.

Ruthlessness and thievery

Using Google to scour Development Seed's blog, I uncovered the meat we needed for several docs and used these as a starting (and sometimes ending) point. This saved me hours. The lesson here is like with most things, great artists steal. Or is it that stealing is the highest form of flattery? I don't know, but just take it (as long as you ask first).

When it came to merging existing documents with the new style and structure, I used the principle of ruthlessness without loss of usefulness. So, anything went as long as no useful information was lost. A lot of the docs were re-written, and many of them were removed or merged into other documents, but any important or useful information in those docs were captured. The idea here is that the goal of docs are to make the way easier for those who are walking down established paths. Signage is important, but consistency helps people find the signs.

Automating everything you can

Tee oh cee

After a while, I started seeing patterns in the documentation I was writing. Nothing as exciting as Mother Mary or Elvis, but for example, to make a table of contents I would copy each heading and paste it into a list at the top of the page.  Then, halfway through I realized that it would be a lot easier for people to link to individual sections in a doc if the headings were clickable. I started to work through each doc again to add the clickable headings and then realized that I must be nuts. Why should I be doing this tedious, repetitive task when I can write a script to do it? And I wouldn't have to worry about changing the structure later on, I could just update my script. And aren't I a developer, shouldn't I be developing? Please, give me some code to write!

So, I wrote a script to add the table of contents and clickable headings. You could roll a doc through it again if you changed some headings or structure, and it would refresh everything. Okay, cool. Now what else could I automate?

See regex run also

We wanted a "see also" section at the bottom of each doc to point users to other related resources. At first, I would read through the doc and pull out the links I found, navigate to the page, figure out what the page was about, and add it to the section. And I thought the table of contents was tedious!

I updated the script to scour the doc for links (a little regex action), and then go out and fetch the title from each page and create a list. As an added bonus, it would check if the page was another local documentation page and add that to a separate "related pages" section.

Crummy bread

Another thing that was tedious and difficult to pin down was breadcrumb / path styling. I wish I had run into this section of the drupal.org handbook style guide before hitting this bump.  But, after some experimenting, it seemed like the Administer > Site  building > Modules (admin/build/modules) structure was the easiest to read (this style was inspired by some docs written by Young). It still was a little painful to write out, and what would we do if we wanted to change the style to something else later? To answer this, I added another bit to the script to search for paths within 

<span class="crumb"></span>

tags and format it. So, you start with: 

<span class="crumb">admin/build/modules</span>

 and it turns it into the full breadcrumb. If the formatting changes, I just change the script and we roll the doc through it again. Easy peasy.

Markdown to HTML to Markdown to HTML to...

Next was the issue of how to post Markdown-based docs on Drupal.org, which only supports HTML. And, what if we wanted to run the new HTML docs through this script to update the table of contents or see also section? Up to this point, it only supported Markdown.

The answer was pretty straightforward. I integrated the Markdown for Markdown to HTML conversion as well as Markdownify for converting HTML to Markdown. I had to do a little hacking of Markdownify because it would use a Markdown syntax that uses URL references instead of inline URLs, which I find makes editing URLs a huge pain.

Headings and stuff

Oh yeah, and you know how in community documentation, headings seem to be all over the place? H2 here, H9 there? Well, I added a setting to convert all headings to the heading of your choice. Also, have you noticed that some of us use "quotes" for emphasis? There's also a setting to turn all in-text quotes to bolding. An em tag would make more semantic sense, but when you're reading through a doc, the bold seems to work better for actual emphasis.

Beautify your docs too!

All this automation was too much to squander on a measly hundred docs, so I cleaned up the script interface, added some clouds and rainbows, and spent a day turning it into BeautifyMyDocs.com. This means that if you want to leverage these tools for docs on drupal.org, or your own doc project, you can! It kind of makes you feel good, too.

I will be posting more about BeautifyMyDocs.com soon.

Attribution

In any good doc, it's good to attribute your sources, either to give them thanks or to lend your doc credibility. In this case, I'm invoking the Development Seed name to give thanks. I really enjoyed getting to know Open Atrium and Managing News, and the DS folks made it happen, so many thanks to them. Special thanks to Ian Ward for fielding all my questions (of which there were more than a few).

Sep 28, 2010

Internet Explorer has a 31 file limit on stylesheets. So, if you've got 242 CSS files like some Drupal sites out there, then 210 of them won't load, and your site will be this funky combination of some CSS, but not all of it.

John Albin as put together a nice writeup on the issue, along with possible solutions for Drupal sites. He also built the IE CSS Optimizer module that solves the problem for Drupal sites by aggregating the more static stylesheets into one to free up the other slots for theme building and such. Here's a link to the discussion of this problem on drupal.org (299 comments!).

Now, this has already been written about a bunch, but it took me a minute or two to track down some good links to pass onto a client, so I'm throwing this up in the hopes that it helps someone else. The first time I ran into this issue, it took me HOURS to figure it out.

Aug 30, 2010

From time to time there's a bit of a sour post in an issue queue or blog post that makes it clear that there are misunderstandings about how the Drupal community works, and in this case it was a disgruntled post regarding lack of support for a particular module. It got my blood a-boil, and this was my response after I calmed down a bit:


Mr. Anonymous,

Perhaps it's the language gap, but your posts are coming across pretty harsh. Or, maybe you're just figuring out how parts of the Drupal space actually works and you're frustrated by it. That's understandable - it's tough realizing that Drupal isn't actually run by a team of tireless developers with infinite patience and no bills to pay - and I don't mind bearing the brunt of your frustration if I can help you and other folks in your shoes come to terms with a more accurate perspective.

From a user's point of view, in the ideal world every developer would have the time and desire to regularly pummel their issue queues into submission (like some people). In the developer's world, things look a little different. Most of us have enough going on that we have to prioritize what gets done, and that depends on a huge number of factors, including but not limited to:

  • Can the module / community work be integrated into client work? (i.e. killing two birds with one stone)
  • What kind of time is there beyond client work (i.e. bill-paying work) is there to work on other projects?
  • Out of the numerous projects that you have on your plate, which ones are the most important strategically in getting you closer to your longer-term goals?
  • How many people will be affected by your work?
  • Who are the people will be affected by your work?
  • How educational or exciting is the work going to be?

I may be speaking just for myself, but I'm not positively influenced by how upset a single community user gets about poor support. That sort of reaction means that the user probably has some other pressures in their life impacting their overall happiness and they aren't going to get an awful lot happier through you responding to their demands. So posts like yours above beget the opposite reaction to what you were probably hoping for. I'm actually less enthusiastic about tackling the issues you mentioned, not out of spite, but just because I can't help but get a little bummed out.

Each module on Drupal.org has a backstory, and some of those stories involve a developer who actually is tireless and is doing this work only because of a pure desire to make Drupal better and push their own skills, and it's this focus that allows them to put a strong focus on supporting the module, regardless of who asks or what they're getting paid.

There are other situations where a developer creates a module because they are asked to do so for a client - as with this particular module. What I was actually asked for was a particular feature, and upon my suggestion the client generously agreed to sponsor the extra time that would be required to make the feature modular and share it on Drupal.org - i.e. they understood the value of sharing. I wouldn't have built this module without the financial support because I don't have enough use cases to justify the time required. So my motives are around making the client happy while sharing as much of the work as I can with others.

Now here's the next part of the equation, which is where you come in. You found a good use case for the module - which is great, but doesn't mean that it changes how or when I can work on it. Because the code is open source and free to use, however, you now have the ability to actually go in and fix those problems you've found, or find someone who has the skill set to do so. You're free! You're not beholden to my currently limited ability to offer support, you can actually take action and get something done. And I'd say that in contrast to what you suggested Drupal was all about, that this is a lot closer. It's people doing what they can, when they can, as they need to, and sharing it all.

Good luck!
Chris

Aug 24, 2010

Upgrading Drupal from one minor version to the next can be time-consuming and error prone. A lot of folks use Drush for this, but a good second choice for the commandlinophobic is to use a patch file. 

Bernhard Fürst creates patches from all previous minor versions of Drupal 5 and 6 to the current release and posts them here. I've used this method several times, and it's gone really smooth.

First, go to your sites /admin/reports/updates page and see what version of Drupal you're running. Here's what mine looks like:

So, I'm on 6.16 and need to upgrade to 6.17.

Next, go to the list of patch files and find the one that matches up with your version. Click on it to download:

Move the downloaded patch to your Drupal site's base directory.

Now, we need to move to the command line. Sorry, commandlinophobes.

First, cd to the directory where you just put the patch file.

Before we run the patch for real, we're going to do a quick dry run to make sure that we don't get any errors. You'll need to use the actual patch file name you downloaded:

patch -p1 --dry-run < drupal-6.16-to-6.17.patch

You'll see a list of everything that gets patched. If you see any errors having to do with HUNKs, then you should probably use another method to upgrade.

If everything looks good, then run the patch for reals:

patch -p1 < drupal-6.16-to-6.17.patch

Now, run /update.php.

Update: Check out an article Kalid posted in the comments that shows how to automate this process via the command line. It's more command line-heavy, and if you're going to get that heavy it's just a tiny step over to using Drush, but is still pretty cool.

Here's some additional information about upgrading if you run into issues:

The drupal.org handbook page on upgrading with patches
The drupal.org handbook page on upgrading in general
The list of patch files
* Also reference the UPDATE.txt file in your Drupal site's main directory for more information

Aug 13, 2010

The other day I got a message today from killes that the Drupal Planet was getting a ton of 404 errors on the images in my posts because I was using relative URLs, and because I've been going a bit gangbusters on the imagery lately, the errors have been compounded. These 404 errors pollute the error logs, making is more difficult to identify important errors, and apparently I'm not the only one with this issue. You, too, could be responsible for log pollution!

Luckily, I ran into a module called Relative Path to Absolute URLs a while back when figuring out how to send launch MailChimp campaigns from Drupal (module forthcoming) that will add an input filter to convert relative URLs in your images and links to absolute ones. So, I installed it, enabled the filter, and all was well with the Planet.

If you're contributing to log file wash-out with relative paths, use Relative Path to Absolute URLs and help keep the Planet clean.

Syndicate content Syndicate content Syndicate content Syndicate content Syndicate content