September 2010

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.