BlogmyQuery – BMQ

If you’re a plugin developer and you just love to write code, then writing a readme.txt file for a plugin in WordPress’ repository might be your idea of hell. When you’ve written all of that lovely code, why must you spend time writing about how to use it?

Unfortunately, some plugin developers view writing a readme.txt file as the least important part of their job. So, we end up with things like the following:

• Descriptions with only one line,
• Descriptions with hardly any information,
• No translation into English,
• Typos,
• Confusion.

Why You Should Care About Your Readme.txt

A poorly written readme.txt does not necessarily indicate that the plugin is poorly written; the code could be mind-blowingly good. But it does give the impression of an overall lack of attention to detail and a lack of care for end users. You see, no one will notice if a readme file is particularly awesome, but they will notice if it’s bad.

You needn’t view the readme file as pain-in-the-butt homework that you’ve got to do after all the fun you’ve had with coding. A readme benefits you. Here’s how:

• Gives you an opportunity to say why your plugin is so good,
• Shows off your plugin’s features,
• Makes it easy for users to install and use the plugin,
• Anticipates support questions with a thorough FAQ,
• Links to your website and other products,
• Upsells your commercial services.

In this article, we’ll look at how to improve your WordPress readme file so that it benefits both your users and you.

But first, the mechanics.

Using (Quasi-)Markdown

Markdown is a text-to-HTML conversion tool, developed by John Gruber and Aaron Schwartz, that is used for readme files of plugins in the WordPress repository.

You write the readme in Markdown, and Markdown will convert it to HTML for the WordPress directory page, but it will still look good in WordPress’ back end and when you peek at it in your favorite text editor.

Take a look at the directory page for Simple Twitter Connect:

Simple Twitter Connect’s listing in the WordPress plugin directory.

Here’s how it appears when I download and extract the readme:

Simple Twitter Connect’s readme file in Notepad.

And here’s how it appears in WordPress’ back end:

Simple Twitter Connect’s readme on the “Edit Plugin� page in the WordPress Dashboard.

It is readable no matter what medium it is viewed in. Imagine how difficult reading the readme in a text editor would be if it was marked up in HTML. Markdown makes your readme clear, readable and semantic.

WordPress.org uses what Mark Jacquith describes as quasi-markdown. It basically works like markdown, and much of the syntax is the same, but there are a few important differences, particularly in the headers.

To get you started with your WordPress readme, here’s a table containing the syntax that you’ll need.

Now that you know how to write in WordPress-flavored Markdown, let’s get started writing a readme.

Writing Your Readme.txt

Writing a readme is not hard, but putting a bit of thought into it beforehand does pay off.

• What do you think end users will need in order to get optimal use from your plugin?
• Do you need to include any special instructions or code snippets?
• What problems do you anticipate users running into?
• How can you make your plugin as attractive as possible?
• In a saturated market, what makes your plugin stand out?

With a bit of thought, you can produce a useful readme that shows off the best aspects of your plugin.

When writing the readme, remember that if people are able to use your plugin properly, then they will be less likely to come knocking on your door asking for help.

Let’s look at each of the main readme sections to see what you can do to improve it. As a reference point, we’ll use the readme for Simple Twitter Connect, which is concise, useful and well-formed.

Plugin Header

The plugin’s header contains basic information about your plugin that the user will take in at a glance. This information will be displayed in the plugin’s directory as a quick reference for users.

Here’s what you’ll need to complete it:

• Contributors
  Anyone who has contributed to the plugin. You should use a contributor’s user name from WordPress.org, linking it to their WordPress.org profiles, which list all of the contributor’s plugins. Unfortunately, many developers don’t mention their WordPress user name, which means they miss out on the opportunity to showcase the rest of their work.
  
  A contributor tag done right.
  
  A contributor tag done wrong.
• Donate link
  This is your chance to get a little something back from the WordPress community. If you don’t have a donate link, you aren’t giving people the opportunity to thank you!
• Tags
  As on a blog, tags are used to categorize content. In a directory of 15,000+ WordPress plugins, using tags effectively makes it easy for people to find your plugin. Keep the tags relevant, and think of what people who need your plugin might be searching for. Some developers tag their plugins with words that are only tangentially related.
  
  This listing for the Twitter tag isn’t helpful because it’s bloated with irrelevant content. As WordPress community members and contributors, we have a responsibility to keep the directory of plugins as intuitive as possible.
• Author URI
  Your home page.
• Plugin URI
  The plugin’s home page. Note that the Author URI and Plugin URI aren’t included in the readme template provided by WordPress. Including them is definitely a good thing because they direct people to your respective home pages.
• Requires at least
  This is the version of WordPress that your plugin requires. Some people don’t upgrade WordPress (some for valid reasons and some for dumb reasons). Tell them whether WordPress will work with their version.
• Tested up to
  Another piece of important information. This tells people which version of WordPress your plugin has been tested up to.
• Stable tag
  The stable tag tells WordPress which version of the plugin should appear in the directory. This should be in numeric format, which is much easier for WordPress to deal with. Aim for numbers like 1.5, 0.5 or whatever version you’re at. If your stable version is in the trunk in Subversion, then you can specify “trunk,� but that is the only time you should use words instead of numbers.

Here’s what the header information for Simple Twitter Connect looks like:

=== Simple Twitter Connect ===
Contributors: Otto42
Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=otto%40ottodestruct%2ecom
Tags: twitter, connect, simple, otto, otto42, javascript
Requires at least: 3.0
Tested up to: 3.2
Stable tag: 0.15

Tips for Writing Header Information

• Use WordPress.org user names for contributors.
• Use a number for the stable tag.
• Include donation link to make some cash.
• Keep tags relevant.
• Test with the most recent WordPress version.

The Short Description

The short description is what appears on the WordPress.org page that lists plugins.

It also appears in the user’s list of installed plugins:

It’s your chance to craft a punchy 150-character description that will make people want to install your plugin.

Unfortunately, some people miss the mark:

I’m not sure what this one is all about:

None of these short descriptions tell you anything about what the plugin does. They’re totally useless in providing information to WordPress users.

Another problem is when developers do not add a short description at all. In that case, the 150 characters are excerpted from the long description. Check out the short description for Simple TrackbackSimple Trackback Validation with Topsy Blocker:

The short description cuts off in the middle of a word. We know that the plugin performs a test on trackbacks, but why? What for? How?

Short Descriptions That Get It Right

• VideoPress
  “Manage and embed videos hosted on VideoPress. Requires a WordPress.com blog with the VideoPress premium upgrade.�
• Yet Another Related Posts Plugin
  “Display a list of related entries on your site and feeds based on a unique algorithm. Templating allows customization of the display.�
• BuddyPress
  “Social networking in a box. Build a social network for your company, school, sports team or niche community.�
• The Google+ Button
  “Adds the Google +1 button to your site so your visitors can vote to tell the world how great your site is!�

Tips for Writing a Short Description

• Stick to under 150 characters.
• Don’t rely on the text being pulled from the long description.
• Tell people what the plugin will do for them.
• Don’t worry about technical details. You can provide them in the long description.
• Tell people whether the plugin has any requirements to work, such as a subscription.

Long Description

The long description is where you really go to town. You’ve hooked people with the short description; now it’s time to sell your plugin. Let’s check out the long description for Simple Twitter Connect:

== Description ==
Simple Twitter Connect is a series of plugins that let you add any sort of Twitter functionality you like to a WordPress blog. This lets you have an integrated site without a lot of coding, and still letting you customize it exactly the way you’d like.

First, you activate and set up the base plugin, which makes your site have basic Twitter functionality. Then, each of the add-on plugins will let you add small pieces of specific Twitter-related functionality, one by one.

Bonus: Unlike other Twitter plugins for WordPress, this one helps you create your own Twitter application and identity, so your tweets from here show up as being from Your Blog, not from some plugin system. You’ll never see "posted by Simple Twitter Connect" in your tweet stream, you’ll see "posted by Your Blog Name". Great way to drive traffic back to your own site and to see your own Twitter userbase.

Requires WordPress 3.0 and PHP 5.

**Current add-ons**
* Login using Twitter
* Comment using Twitter credentials
* Users can auto-tweet their comments
* Tweet button (official one from twitter)
* Tweetmeme button
* Auto-tweet new posts to an account
* Manual Tweetbox after Publish
* Full @anywhere support
* Auto-link all twitter names on the site (with optional hovercards)
* Dashboard Twitter Widget

**Coming soon**
* More direct retweet button (instead of using Tweetmeme)
* (Got more ideas? Tell me!)

If you have suggestions for a new add-on, feel free to email me at otto@ottodestruct.com.
Want regular updates? Become a fan of my sites on Facebook!

http://www.facebook.com/apps/application.php?id=116002660893

http://www.facebook.com/ottopress

Or follow my sites on Twitter!

http://twitter.com/ottodestruct

What makes this a good example of a long description?

1. The opening description is clear and useful. It tells you what the plugin does and how it works.
2. The key features stand out (you can tell that the plugin creates your own Twitter app).
3. The plugin’s requirements are listed.
4. Markdown is used to break up the text into sections and lists, making it easier to read.
5. All current features are listed.
6. Planned features are listed.
7. The developer has included links to his Facebook page and Twitter account.

A good long description is useful and relevant. It tells the user what the plugin does and how it does it, and it provide anything else that the developer feels is important. You can also use it to send users to your home page or social-media profiles.

Here are some other plugins with great long descriptions:

• EG Attachments
• Google Maps All-in-One
• Next Gen Gallery

Tips for Writing a Long Description

• Use Markdown to bring some variety to the formatting. For example, add headings to break up sections, use lists, and put important points in bold.
• Be clear about the plugin’s features.
• Include any requirements, such as other plugins that your plugin relies on, or specific PHP versions.
• Link to any extended documentation on your website.
• Don’t be afraid to link to your website or social profiles.
• If you’ve got one, a video is a great demonstration tool.

Installation

The installation section should include everything that a person needs to get the plugin up and running correctly. Often, you can keep this brief. Check out the instructions for Simple Twitter Connect:

1. Upload 'plugin-name.php' to the '/wp-content/plugins/' directory,
2. Activate the plugin through the 'Plugins' menu in WordPress.

For many plugins, this will suffice. But some plugins need detailed instructions. Check out the ones for these:

• WP Super Cache,
• WordPress MU Domain Mapping.

Users need mammoth instructions to set up both of these plugins. WP Super Cache requires you to look in your .htaccess file, and Domain Mapping needs you to move files to /wp-content/ and to edit wp-config.php.

Tips for Writing Instructions

• Be brief, a few lines if possible.
• Include everything the user needs to install the plugin.
• Make sure each step logically follows the preceding one.
• Include any code snippets that the user might need.
• Be clear and concise. This is the place for instructions, not sales.

FAQ

The FAQ (frequently asked questions) section is your opportunity to troubleshoot problems before they even get posted to WordPress’ support forums. OK, so a few people will probably never bother looking at the FAQ to see whether their question is addressed there, which is annoying, but at least you will be able to direct them to the FAQ.

Some FAQs, however, are pretty lousy. In fact, some plugins, even popular ones, lack any FAQ at all. This is a problem: if too many plugin developers don’t include an FAQ, then some WordPress users will assume that plugins normally don’t have one and will run straight to the support forums. This wastes the time of people who have taken the trouble to include an FAQ.

Let’s check out the FAQ for Simple Twitter Connect:

== Frequently Asked Questions ==

= Whoa, what's with all these plugins? =
The principle behind this plugin is to enable small pieces of Twitter functionality, one at a time.

Thus, you have the base plugin, which does nothing except to enable your site for Twitter OAuth in general. It's required by all the other plugins.

Then you have individual plugins, one for each piece of functionality. One for enabling comments, one for adding Login, etc. These are all smaller and simpler, for the most part, because they don't have to add all the Twitter connections stuff that the base plugin adds.

= The comments plugin isn't working! =

You have to modify your theme to use the comments plugin.

In your comments.php file (or wherever your comments form is), you need to do the following.

1. Find the three inputs for the author, email, and url information. They need to have those ID's on the inputs (author, email, url). This is what the default theme and all standardized themes use, but some may be slightly different. You'll have to alter them to have these ID's in that case.

2. Just before the first input, add this code:
[div id="comment-user-details"]
[?php do_action('alt_comment_login'); ?]
(Replace the []'s with normal html greater/less than signs).

3. Just below the last input (not the comment text area, just the name/email/url inputs, add this:
[/div]

That will add the necessary pieces to allow the script to work.

Hopefully, a future version of WordPress will make this simpler.

= Twitter Avatars look wrong. =

Twitter avatars use slightly different code than other avatars. They should style the same, but not all themes will have this working properly, due to various theme designs and such.

However, it is almost always possible to correct this with some simple CSS adjustments. For this reason, they are given a special "twitter-avatar" class, for you to use to style them as you need. Just use .twitter-avatar in your CSS and add styling rules to correct those specific avatars.

= Why can't I email people who comment using Twitter? =

Twitter offers no way to get a valid email address for a user. So the comments plugin uses a fake address of the twitter's username @fake.twitter.com. The "fake" is the giveaway here.

= When users connect using Twitter on the Comments section, there's a delay before their info appears. =

Yes. In order to make the plugin more compatible with caching plugins like WP-Super-Cache, the data for a Twitter connect account is retrieved from the server using an AJAX request. This means that there will be a slight delay while the data is retrieved, but the page has already been loaded and displayed. Most of the time this will not be noticeable.

= Why does the settings screen warn me that I don't have a URL shortener plugin? =

Simple Twitter Connect does not implement a URL shortening service in favor of letting other plugins implement one for it. WordPress 3.0 includes a new shortlink method for plugins to implement this properly.

A shortener plugin should implement the "get_shortlink" filter for it to be detected. WordPress 3.0 will be required for this to work.

The WordPress.com stats plugin implements this, and it provides shortlinks to "wp.me" URLs. If you wish to use another shortener plugin, tell that plugin's author to implement this same standard, and the plugin will automatically be detected and used by Simple Twitter Connect.

That’s a pretty thorough FAQ! It’s useful because it anticipates any questions a user might have. It’s a pre-emptive strike: get in there with the answers before you see anxiety explosions in the support forums.

When writing support documentation such as an FAQ, aim at the lowest common denominator. A developer who is using your plugin likely won’t need an FAQ, and if they do, they’ll probably get the gist of it quickly and be able to implement it in an instant. There’s a rumor going around that WordPress is easy to use, which means that a lot of people who don’t know a whole lot about code will be fiddling around with it and break stuff. They are the people to whom you should be addressing your documentation, because they’ll be giving you the biggest headaches in the support forums.

Tips for Writing an FAQ

• Anticipate issues and answer them in advance.
• Deal with any known conflicts with old WordPress versions or other plugins.
• If a problem recurs in the support forums, add it to your FAQ.
• Use Markdown to highlight each question and follow it with an answer.
• Include any code snippets or shortcodes that the user might need.
• The FAQ is a tool to help you. Use it properly, and save some money on Aspirin.

Screenshots

Unfortunately, many developers think that screenshots are the realm of theme designers. Perhaps you assume that there’s nothing exciting or sexy to see in your plugin, so why bother providing screenshots? Check out the screenshots for Simple Twitter Connect. They show both the UI and the front end of the plugin, giving you an idea what it will be like before installing it.

Screenshots help users decide whether a plugin is right for them. As a developer, you might not think your UI is particularly interesting, but as an end user, I like to look at the settings before installing a plugin. It might not be a deal-breaker, but it does help me decide.

Here are some plugins with nice screenshots:

• Social Profiles Sidebar Widget
• WP Page Navi
• Next Gen Gallery

Tips for Putting Together Screenshots

• Name screenshots as screenshot-1.png, screenshot-2.png, etc.
• Include at least one screenshot of the UI, and one of what it does in the front end (if it does anything there).
• Keep the size of the screenshot file small.

Other Notes

Including “Other Notes� is not essential. Many plugins don’t have them; Simple Twitter Connect doesn’t, for instance. But the section is useful if you have additional information that doesn’t necessarily fit in any other section.

Things You Can Include in “Other Notes�

• Credits
• To-do list
• Localizations
• Filters
• Set-up guide
• Requirements
• External links
• Upgrading information
• Licence

Changelog

A changelog, as you would guess, is a log of all changes you’ve made to the plugin. It is an important part of the documentation and shouldn’t be ignored. A changelog may not make for the most exciting reading, but it is helpful. It tells a user what changes have been made to a plugin, and it makes clear why the user should update. It’s also useful for tracking the development of the plugin over time. A changelog gives a plugin context and history, and that can be important for people running big projects or important client websites.

Here’s a scenario: a user sees an alert in the admin area telling them that they need to update a plugin.

This user needs to update WP Touch!

The changelog shows the changes, so that the user can decide whether to update.

The changelog helps us decide.

Maintaining some websites is a balancing act, and some administrators don’t want to upgrade unless absolutely necessary (say, for security updates or for new must-have features). Give them the information they need to be able to decide for themselves. If the update is minor, they might decide to save themselves the hassle and wait until something major arrives.

The changelog for Simple Twitter Connect is lengthy, not surprisingly. You’ll see all of the minor and major changes that have been made. Being able to see this plugin’s history and development is so useful.

Tips for Writing the Changelog

• No change is insignificant. Make sure to add every single change.

Conclusion

Underestimating the importance of the readme file does a disservice to your code and to the WordPress community; so, seeing so many plugin developers do just that is sad. Don’t fight the readme: embrace it. It’s an important part of your documentation. A good readme is useful, helping users get set up to use the plugin as effectively as possible. And it’s useful to you, the developer. The readme demonstrates your plugin and anticipates problems, and it’ll save you time and headaches with support requests.

Here are some useful resources to get your plugin ready for the WordPress repository:

• WordPress readme.txt template
  The readme.txt template provided by WordPress.org. Download it and stick your readme text in it to get started.
• WordPress readme.txt validator
  Validating your readme before submitting it is helpful. This tool will flag any issues so that you can get it just right.
• WordPress Plugin Readme File Generator
  Feeling lazy? If you would prefer to fill in a form than write up a readme.txt file, try this generator.
• “How to Publish to the WordPress Plugin Repositoryâ€�
  There’s more to publishing in the repository than writing a readme. This tutorial takes you through the steps to getting published.
• “How to Write a WordPress Plugin: 12 Essential Guides and Resourcesâ€�
  Haven’t even started writing your plugin yet? Check out this collection of plugin development resources.

(al)

© Siobhan McKeown for Smashing Magazine, 2011.

The Web is just starting to use animation well. For years, animated GIFs and Flash ruled. Text moved and flashed, but it was never seamless. Animations had boxes around them like YouTube videos. HTML5 canvas changes everything about Web animation.

The canvas element makes it possible to integrate drawings and animations with the rest of your page. You can combine them with text and make animations interactive. This drawing mechanism is powerful, but very low-level.

Animations get more power and need less coding when you combine the canvas tag with higher-level libraries such as Paper.js. This article introduces HTML5 animation and walks you through creating an animation of dandelion seeds blowing in the wind.

Neat Is Easy, But Messy Is Hard

Computers love clean. They make spreadsheets, do statistics and plot multivariate curves; they always color inside the lines.

In the real world, even simple things are messy. Leaves falling from trees, water splashing — all the little interactions around us feel simple because we’re used to them; but little bursts of wind are actually messy and unpredictable.

For this article, we’ll animate dandelion seeds blowing in the breeze.

Dandelions are tricky because we all know what they look like: we’ve touched them and blown their seeds off. Commonplace objects produce instant recognition and feelings. I don’t have to tell you what dandelions are — you just know. Dandelions are a chaos of seeds piled on top of each other.

(Image: Arnoldius)

Our dandelion animation will never reproduce the complexity of the real thing, and it will work better if we don’t try: make it too close to real and it will feel funny. Instead, we’ll create a stylized dandelion that makes the right impression without all of the details.

Paper.js

Drawing simple shapes with the canvas tag, without any special drawing libraries, is easy. Create your canvas:

<canvas id="canvas" width="300" height="300"></canvas>

Then add a little JavaScript.

// Get our canvas
var canvas = $('#canvas')[0].getContext("2d");

// Draw a circle
canvas.beginPath();
canvas.arc(100, 100, 15, 0, Math.PI*2, true); 

// Close the path
canvas.closePath();

// Fill it in
canvas.fill();

Cheat sheets for canvas show you the basics, but when you get into more serious drawing, you’ll want a higher-level library, such as Paper.js.

Paper.js is a JavaScript library for drawings and animations. It’s based largely on Scriptographer, a scripting language for Adobe Illustrator. You can write JavaScript with Paper.js, but most of the time you’ll be working with a JavaScript variant called PaperScript.

Paper.js calls itself “The Swiss Army Knife of Vector Graphics Scripting,� and the “vector� part is important.

There are two basic types of graphics, vectorized and rasterized. Rasterized graphics are like the pictures you take with your camera: big rectangles with maps denoting the color of each pixel. Enlarge them and you’ll get blurry dots.

Vector graphics are like connect-the-dots pictures: they’re sets of lines and shapes that give instructions on how to draw the image at any size. Using vector graphics, you can make an image of the letter Z really big and it will still look sharp. If you turned it into a rasterized graphic by taking a picture of it and then blowing it up, the letter would get all blurry.

Vector graphics libraries are perfect for animation because they make resizing, rotating and moving objects easy. They’re also much faster, because the program has instructions for drawing each object instead of needing to figure it out.

The Paper.js examples page shows some of the amazing things you can do with vectorized graphics.

The dandelion is a complete functioning example, and you can see it all running on the example page. You can also change the code by clicking the “Edit� button, see your changes live, and copy and paste the code to your own website. Over the course of the article, we’ll explain each part of the code in turn, but please note that in order to run the code yourself, you will need to head over to the example page and copy and paste it to your own environment.

Drawing Our Dandelion

The first step is to import our JavaScript and PaperScript files.

<script src="paper.js" type="text/javascript" charset="utf-8"></script>
<script type="text/paperscript" canvas="canvas" src="dandelion.pjs" id="script"></script>

The PaperScript code for running the animation is declared as text/paperscript. Now we’re ready to start drawing.

The first part of our dandelion is the stem. The stem is the green arc, with a circle on the top for the bulb. We’ll make both shapes with a path, a list of shapes, points and lines that the browser is instructed to display.

Paths are the basic building blocks of animation. They render lines, curves and polygons. You can also fill them in to make complex shapes. Our path looks like this:

var path = new Path();
path.strokeColor = '#567e37';
path.strokeWidth = 5;

var firstPoint = new Point(0, 550);
path.add(firstPoint);

var throughPoint = new Point(75, 400);
var toPoint = new Point(100, 250);
path.arcTo(throughPoint, toPoint);

Our path is an arc, so it needs three points: the start, the end and a midpoint to arc through. Three points are enough to define any arc we need. The arcTo function draws the line between them. The path item also supports styling information, such as stroke color and stroke width; #567e37 and 5 will make our arcing line green and thick. Paper.js supports the same color definitions as CSS.

We can add a few more items to make it all easier to see:

path.fullySelected = true;

var circle = new Path.Circle(throughPoint, 5);
circle.fillColor = '#CC0000';

Fully selecting the path will display some lines to show us the arc; the red circle shows us where the through point is.

The stem ends with a circle to show the bulb of the flower and give us a place to attach all of the seeds. Circles are much easier in Paper.js than in direct canvas.

var bulb = new Path.Circle(toPoint, 10);
bulb.fillColor = '#567e37';

One line of code draws our circle, one more makes it green, and now we’re ready to add our seeds.

Drawing The Seeds

Each seed has a bulb, a little stem and a wispy part on top.

(Image: Hmbascom)

Our seed starts with a small oval for the bulb and an arc for the stem. The oval is a rectangle with rounded corners:

var size = new Size(4, 10);
var rectangle = new Rectangle(p, size);
var bottom = new Path.Oval(rectangle);
bottom.fillColor = '#d0aa7b';

The seed stem is another arc, but this one is much thinner than the flower stem:

var stem = new Path();
stem.strokeColor = '#567e37';
stem.strokeWidth = 1;
stem.add(new Point(p.x + 2, p.y));

var throughPoint = new Point(p.x + 4, p.y - height / 2);
var toPoint = new Point(p.x + 3, p.y - height);
stem.arcTo(throughPoint, toPoint);

The wisps are more arcs with a circle at the end of each line. Each seed has a random number of wisps that start at the top of the stem arc and curve out in different directions. Randomness makes them look a little bit messy and thus more natural. Each seed gets a random number of wisps, between 4 and 10.

for (var i = 0; i < random(4, 10); i++) {
    path = new Path();
    path.strokeColor = '#fff3c9';
    path.strokeWidth = 1;

    var p1 = new Point(p.x, p.y);
    path.add(new Point(p1.x + 2, p1.y + 2));

    // Each flutter extends a random amount up in the air
    var y = random(1, 5);

    // We draw every other stem on the right or the left so they're
    // spaced out in the seed.
    if (i % 2 == 0) {
        throughPoint = new Point(p1.x + random(1, 3), p1.y - y);
        toPoint = new Point(p1.x + random(5, 35), p1.y - 20 - y);
    } else {
        throughPoint = new Point(p1.x - random(1, 3), p1.y - y);
        toPoint = new Point(p1.x - random(5, 35), p1.y - 20 - y);
    }

    path.arcTo(throughPoint, toPoint);

    // Now we put the circle at the tip of the flutter.
    circle = new Path.Circle(toPoint, 2);
    circle.fillColor = '#fff3c9';
}

Now that we’ve drawn the seed, we need to manage it; later, we’ll want to move and rotate it. The seed is made up of a lot of parts, and we don’t want to have to manage each one separately. Paper.js has a nice group object. Groups associate a set of objects together so that we can manipulate them all at once.

var group = new Group();
group.addChild(bottom);
group.addChild(stem);

this.group = group;

The last step is to package our seed into a reusable object called Seed. We add all of the code we’ve been writing to a new function with the name Seed and add a function to create the initial variables. This example calls that function create, but you can name it anything you want.

function Seed() {

    this.create = function (/*Point*/ p, /*boolean*/ shortStem) {
    …

The create function draws the seed at the specified Point, and the shortStem boolean tells us whether this is a short stem. We’ll look at short-stemmed seeds a little later.

These types of functions don’t work as constructors in JavaScript, but are supported in PaperScript.

var seed = new Seed()
seed.create(new Point(100, 100), false);

Our seeds will look like this when we draw them:

The Seed object draws our random dandelion seeds. Now we can add them to our flower.

Adding A Little Chaos

The seeds will look better when we space them out around the circle of our dandelion bulb to feel like a halo of seeds. The bulb is a circle, and the circle is a path, so we can get each point on the path.

var bulb = new Path.Circle(toPoint, 10); bulb.fillColor = '#567e37';

var angle = 360 / bulb.length;
var seeds = [];

for (var i = 0; i < bulb.length; i++) {
    var seed = new Seed()
    seed.create(bulb.getPointAt(i));

    // Rotate each seed so that it points out from the bulb
    seed.rotate(i * angle);
    seeds.push(seed);
}

This will make a circle of seeds around the bulb but leave a space in the middle. We’ll add a few more seeds to fill in the center. We’re giving the center seeds short stems so that they show the white of the wisps more than the beige of the stems.

for (var i = 0; i < 18; i++) {
    var seed = new Seed()
    var point = new Point(toPoint.x + random(-3, 3),
                          toPoint.y + random(-3, 3));
    seed.create(new Point(toPoint), true);
    seed.rotate(random(0, 360));
    seeds.push(seed);
}

The seeds in the middle will bunch randomly and make our dandelion look nicely messy. Now we can make them blow off.

Animating The Seeds

Wind pushes seeds in complex patterns, and two seeds will never blow off the same way. We want to make them look real, so we’ll need a little more randomness.

Reproducing real wind is much too complicated, so we’ll make the seeds float off in a random-looking pattern. Each seed is assigned a random point on the right side of the screen as a final destination:

this.dest = new  Point(1800, random(-300, 1100));

The rotateMove function pushes each seed toward its destination point and rotates it. We can work with our Seed object as a group to rotate and move it with one function.

this.rotateMove = function(/*int*/ angle) {
    if (this.group.position.x < 850 && this.group.position.y < 650) {
        var vector = this.dest - this.group.position;
        this.group.position += vector / 150;

        this.angle += angle;
        this.group.rotate(angle);
    } else {
        this.isOffScreen = true
    }
}

This function will move the seed until it’s off the screen. Calling rotateMove for each frame of our animation will make the seed float across the screen.

Paper.js gives us an easy way to make animations with the onFrame function; when we implement onFrame, Paper.js will call it for every frame of our animation. With each frame, we iterate over each seed and move it across the screen.

function onFrame(event) {
    for (var i = 0; i < seedCount; i++) {
        if (!seeds[i].isOffscreen()) {
            seeds[i].rotateMove(random(2, 4));
        }
    }
}

The seeds slide and rotate a little closer to the destination point with each frame of the animation. Starting all of the seeds at the same point and ending them far apart makes them space out nicely as they move.

We don’t want all of the seeds to fall off at once, so we’ll use a timer to make them drift away.

function start() {
    var id = setInterval(function() {
        seedCount++;
        if (seedCount === seeds.length) {
            clearInterval(id);
        }
    }, 1000);
}

The timer waits for one second before releasing the next seed, giving our dandelion a nice floaty feel.

Some green grass and blue sky as a background image for our canvas puts it all into context. Now we have a dandelion with seeds floating on the breeze.

See the dandelion running here. You can edit and run the source code as part of the animation or download it from the dandelion GitHub page.

Paper.js In The Real World

Paper.js has some impressive examples and a nice coding model, but you should know a few gotchas before using it on your website.

It Doesn’t Work In Old Browsers

All Paper.js drawings use the canvas tag and require HTML5. This means that you need Internet Explorer 9+, Firefox 4+, Safari 5+ or Chrome. If your website must support older browsers, then you won’t be able to use canvas.

There’s no way around this requirement; if you need older browsers, you’re out of luck. As the Paper.js website says, “Let’s go forward!.�

Performance Can Be Slow

Paper.js can make a browser grind to a halt even if the browser supports HTML5. Pixar renders Buzz and Woody on giant server farms — all you get is your user’s cheap MacBook.

Not only are laptops slower than server clusters, but browsers make things worse by rendering the canvas tag with the CPU instead of the GPU. Games like Halo and Rage take advantage of the graphics processor on your video card to render rocket launchers and mutants. The CPU is less efficient with graphics, so the same computer that handles complex video games smoothly can make floating dandelion seeds look slow and jerky.

Make sure to test all of your animations with slower hardware, and watch the CPU usage. Use groups to minimize the calculations, and be very careful about what you do in each invocation of the onFrame function.

Mobile Devices Are Slower

Mobile performance is even worse. Most mobile devices support canvas, but they are mostly too slow to render canvas animations well. Even more powerful devices, like the iPad 2, can’t handle the dandelion seeds smoothly.

It Doesn’t Support Object-Level Events

Other drawing libraries, such as SVG (see below), support object-level mouse and keyboard events. Those events make it easy to respond when a path or a polygon is clicked, hovered over or touched.

The canvas tag doesn’t support object-level events. Paper.js has some basic functionality for hit testing, but it’s very low-level. You can listen for mouse and keyboard events on the whole canvas, but you’ll need to handle mapping those events to individual controls.

What About SVG?

The SVG (Scalable Vector Graphics) specification was defined over 10 years ago, but came to the forefront with support libraries such as Raphaël.js, which make it easy to generate SVG images with JavaScript. SVG is powerful, works well for smaller images, and is supported all the way back to Internet Explorer 7 with conversion to VML (Vector Markup Language). SVG is the best choice if you need to support older browsers.

The real issues with SVG are speed, future support and mobile devices. Every browser maker is actively working on making canvas faster. Safari 5 already offers hardware acceleration with the GPU for canvas, and the rest are working on it. SVG is also unsupported on Android devices.

There’s a growing community around canvas, the new technology that vendors are focusing on. They’re adding new features, fixing bugs and making it better every day.

Other Canvas Drawing Libraries

Paper.js isn’t the only option for canvas. Processing.js, from the creator of jQuery, ports the Processing programming language to JavaScript. It supports animations and has many examples.

The three.js engine supports canvas and the WebGL library, and it focuses more on 3-D drawings. Google Dart will also support canvas with built-in rendering objects.

Paper.js is a mature library with a very supportive community on the Paper.js Google Group and many impressive and well-documented examples. Check out some of the amazing things people are doing with it.

More Paper.js Examples

Our dandelion is just the beginning. Below are a few other impressive animations written in Paper.js.

• Examples, Paper.jsPaper.js has a page full of incredible examples. Voronoi is one of the best. Make sure to press the space bar and see the paths. More examples are in the GitHub folder.
• Nardove, Ricardo SánchezJellyfish and a koi pond written with Processing.js. Wait a minute, the jellies are shy.
• “Node Garden in Paper.js,â€� Andrew Berg
• “The HBO Recycling Programâ€�An infographic that I created using Paper.js to show how often different HBO series use the same actors.
• “20 Multi-Touch Gestures You Should Learn Today,â€� Zack GrossbartI created the interactive tutorial with the help of Paper.js.

Where’s your Paper.js amazingness?

(al)

© Zack Grossbart for Smashing Magazine, 2011.

As our technology evolves, so do the industries and professionals driven by it. Painters, once only using brushes and canvas have seen so many amazing new strides in digital painting software over the years, have taken to these new applications like a fish to water. And so many brilliant and inspiring digital paintings have poured from the galleries since. Which is what brings us to this post today.

As most of us in the design field are always looking for inspiring work to share, these digital painters pieces jumped out from the webs, demanding to be featured. So many fantastic paintings reminiscent of the great still life’s of yesteryear, all created with digital effects and brushes. These painter’s precision hold a wealth of inspiration just waiting to be tapped.

Digital Paintings

still life by janaschi

Pomegranate Still Life

Desk Job by algenpfleger

Ceramic and Glass by yumedust

boing boing by algenpfleger

Rose Coffee by depingo

Apple by katzai

Mindcage by I-NetGraFX

Still life by tincek-marincek

Red Queen by Ketka

Night at the Saloon by DawnFrost

Still Life by grey-seagull

Pruity by ebrulii

Horn Cup Spoon Still Life by ATArts

Dragonblood by ELConsigliere

Digital Drawing Still Life 02 by spiritwolf77

Stale Bread by nivalis70

Teapot from photo ref by silvercherry

Still Life by al-nay

1949 by robertmekis

Study Still Life 5 by Tsabo6

Happy New Lunar Year fxEVo

ox ccg silver whistle by skim-milk

White Still Life by cacodaemonia

Merry Urn and Friends by mckadesinsanity

Feather Fruit Skull by KatePfeilschiefter

Study Still Life 1 by tsabo6

Tea Party by sonicaust

Colour Study 2 by TheBlackVerse

Still Life – Fruits by Isra2007

Winter’s End by artcova

Pen and Ink by LancerMoo

Fruit Bowl by saintchase

Heartburn by phantastes

Grapes by CoryTheAnimator

L5R Toturi’s Tactics by higherdepths

after old masters 2 by griffinfly

boy with a coin by Fleana93

The Cowboy by komodoempire

(rb)

Congratulations. You’ve just completed a pixel-perfect mock-up of an app, and you’ve gotten the nod from everyone on the team. All that’s left to do is save the tens, hundreds or maybe even thousands of production assets required to bring it to life.

It’s probably the least interesting part of designing software, usually entailing hours of grinding. Saving images to multiple scales — as required by iOS and other platforms — adds complication to the process. But there are ways to streamline or automate the exporting process.

Copy Merged

Cutting up a design with the “Copy Mergedâ€� feature is fairly easy: ensure that the layers are shown or hidden as needed; draw a Marquee selection around the element; choose Edit → Copy Merged, and then File → New; hit Return; and then “Paste.â€� The result is a new document with your item isolated, trimmed to the absolute smallest size possible.
From here, all you need to do is save the image using “Save As� or “Save for Web & Devices.�

Rinse and repeat for every image needed for the app or website. The technique is simple and quick, but repetitive; and if you ever need to export the images again, you’ll have to start from scratch.

This seems to be the most common method and, for some designers, the only method, which is a shame, because better techniques exist.

You could create an action that triggers the “Copy Merged,â€� “New,â€� “Pasteâ€� process — a small time-saver, but ultimately not much of an improvement to the workflow.

Export Layers to Files

If you’re lucky, and your goal is to export a lot of similar images (typically with identical dimensions), you might be able to use Photoshop’s “Export Layers to Files� script.

By choosing File → Scripts → Export Layers to Files, each layer of the document will be saved as a separate file, with a file name that matches the layer’s name. This means you’ll probably have to prepare the document by flattening all of the elements that you’d like to export down to bitmap layers — a time-consuming process, but often quicker than using “Copy Merged.â€� It could also trim the size of the resulting file, if you choose to remove completely transparent areas.

I can’t say that I’m a fan of the script’s Flash-based UI or of the way it works, but “Export Layers to Files� is handy if your desired result fits its limited range of use cases.

Slices

Photoshop’s Slice tool lets you define rectangular areas to export as individual images, with some limitations: only one set of slices can exist per document, and slices cannot overlap (if they do, then smaller rectangle slices will be formed). During the ’90s, the Slice tool was a good way to create table-based Web layouts, filled with images. These days, designers far more often need finer control over how images are sliced, especially when creating efficient, dynamic designs, typically with images that have transparency. But, with a twist on the original concept, the Slice tool can be put to great use.

Sprite Sheets With Slices

Sprite sheets are commonly used in CSS and OpenGL games, where texture atlasing can have significant performance benefits. A similar method can be employed to build UI elements in Photoshop, even if the result is a set of images, rather than one large image.

By spreading out the elements that you need to export as a flat sprite sheet, you eliminate the need for slices to overlap. If there are too many elements to comfortably fit in one document, you can create multiple documents, eliminating the need for more than one set of slices per document.

The other benefit to working like this is that you’ll no longer need to build your main design documents with the same level of precision. Occasionally using a bitmap or forgetting to name a layer is fine, because you’ll have a chance to fix things when preparing the sprite sheet for exporting. But it does mean that the original mock-up document could get out of sync with the export documents if you make changes (for example, to adjust colors or layer effects).

Because we’re interested only in user-created slices, it might also be a good idea to click “Hide Auto Slices� (in the options toolbar when the Slice Select tool is enabled) and to turn off “Show Slice Numbers,� under “Guides, Grid & Slices� in Preferences. This way, you’ll remove unnecessary clutter from Photoshop’s slice UI.

After you’ve created a sprite sheet with the slices all set up correctly, you’ll be able to export all of the images at once, using “Save for Web & Devices.â€� Assuming you’ve done things correctly, you’ll be able to scale up by 200%, save all of your Retina images, and then batch rename them (adding @2x to the file names) — or scale them down, if you built everything at Retina size to begin with.

Layer-Based Slices

If your UI element is one layer and you’d like the exported image to be the smallest possible size, you might want to consider using a “Layer-Based Slice.� To create one for the currently selected layer, choose “New Layer-Based Slice� from the Layers menu. A Layer-Based Slices moves, grows and shrinks with the layer it’s associated with. It also takes into account layer effects: strokes and shadows increase the size of a Layer-Based Slice, so the effects are included. Less control, but more automated.

My Exporting Workflow

For years, I’ve used Copy Merged as my primary exporting method, and used Export Layers to Files when it made sense. That was a poor choice. Sprite sheets have so many advantages, especially in medium- to large-scale projects, that the set-up time is made up for very quickly. This is even truer when exporting Retina and non-Retina images: each set can be exported in a few clicks and is far less likely to have issues with file names or sizes due to its automated nature.

It also creates an environment in which modifying production assets is easy, allowing for faster iteration and more experimentation. It lowers the barrier to improving artwork during development and when revising the app or website.

And that’s a very good thing.

(al) (il)

© Marc Edwards for Smashing Magazine, 2011.

Right there in the center of my boilerplate for design proposals is a section that I glare at with more resentment each time I complete it. It’s called “Deliverables,� and it’s there because clients expect it: a list of things I’ll deliver for the amount of money that I specify further down in the document. Essentially, it distills a design project down to a goods-and-services agreement: you pay me a bunch of money and I’ll give you this collection of stuff. But that isn’t what I signed up for as a designer. Frankly, I don’t give a damn about deliverables. And neither should you.

(Image: Snoggle Media)

Case in point: for months now, I’ve worked consistently with a particular client for whom I do almost no work on actual design artifacts (wireframes, prototypes, etc.). Rather, I hold frequent calls with the main designer and developer to go over what they’ve done with the product (i.e. poke holes in it) and what they should do next (i.e. help prioritize). Some days, they hand me wireframes; sometimes, a set of comps; other days, live pages. Whatever the artifact, our purpose is always to assess what we have now versus where we need to get to. We never talk about the medium in which these design ideas will be implemented; we focus strictly on the end result, the vision of which we established long ago and continually refer to. And in working this way, we’ve been able to solve countless significant problems and dramatically improve the client’s website and products.

It’s not about deliverables. It’s about results.

Understanding why this works depends on understanding the real role of the designer and the deliverables they create.

A Designer’s Work

First, consider the role of a designer compared to what we actually spend most of our time doing.

What designers are hired to do — the reason why companies seek out designers in the first place — is what my friend Christina Wodtke calls “The Big Thinkâ€�: we’re hired to solve problems and develop strategies, determining what needs to be achieved and making design decisions that help to achieve it. But because companies have a compulsive need to quantify The Big Think, designers end up getting paid to create cold hard deliverables. Our very worth, in fact, is tied intrinsically to how well and how quickly we deliver the stuff. Heck, we’re often even judged by how good that stuff looks, even when much of it goes unseen by a single user.

Is this how it should be done? Absolutely not.

Hiring a designer to create wireframes is like hiring a carpenter to swing a hammer. We all know that the hammer-swinging is not what matters: it’s the table, the cabinet, the deck. Clients don’t hire us to wield hammers, but to create fine furniture. It’s not the process they need or the tools, but the end result.

In theory, companies understand this. In practice, not so much. They cling to the deliverables.

The Essence of Deliverables

So let’s look at what a design deliverable really is.

The purpose of a design artifact, whether a wireframe, prototype or sketch, is to illustrate our thinking. Pure and simple. It’s part of the thinking process. It’s also, according to some, a record to look back on later to aid when reconsidering decisions, tweaking the design and so on. But let’s be honest: people rarely look back at these documents once the design grows legs and starts walking on its own. More often than not, significant changes result in new wireframes, and minor tweaks are made on coded screens, not back in the deliverables that we were paid so much to create.

(Image: HikingArtist.com)

Most of the time, design artifacts are throwaway documents. A design can and will change in a thousand little ways after these documents are supposed to be “complete.� In terms of allocating time and budget, design artifacts can be downright wasteful. They can even get in the way; designers could get attached to ideas as they transition to functioning screens, precisely when they need to be most flexible. Every design is speculation until it’s built.

Like it or not — and some of you will surely disagree — we can survive with fewer deliverables. Of course, what this looks like depends on how you work.

Breaking the Deliverables Habit

The most important parts of any design project are the vision of the end result, the requirements for it, the design itself, and a way to measure its success.

Interestingly, only one of these parts involves complicated design artifacts. The vision is merely a statement that describes the purpose and desired outcome. Requirements are but a list. Success metrics? Another list. The only part that involves more than a simple, concise summary is the design itself. And nothing requires that process to involve layer upon layer of wireframes, prototypes and comps before going to code. (More on how to change this in a minute.)

(Image: lucamascaro)

Comps, of course, are a must when graphics are involved; in addition to necessarily being the source of the graphic files to be used in the actual design, they define the visual language, the specifics of layout, spacing, typography, etc. Creating wireframes, on the other hand, as quick as it is compared to creating coded screens, can take much longer than going from sketch to code. So, consider cutting the load down to what’s most essential and useful: the interaction model.

In other words, you don’t have to create wireframes and comps for every idea or every screen; just for the toughest screens, the ones that define the most crucial interaction paradigms. Use them to iron out the model, not every last detail.

It’s time for more design and less stuff. Consider the revised process below.

1. Strategy Document

Distill your research on users and the business down to a short vision statement on what the user’s experience should be like. Add to this a list of design criteria (specific guidelines or principles for the design), as well as success metrics (how you will know that the design is achieving your goals). You should be able to do all of this within just a couple of pages; and keeping it short will help to ensure that everyone reads it.

2. Activity Requirements

Write a list of tasks that users should be able to perform, and functions that the system should perform that will benefit users. Prioritize the ones that will appear on the screen.

3. Sketch

To apply the design criteria and meet (or exceed!) the requirements, sketch a dozen or so ideas — in Keynote, on paper or on a whiteboard — and then take pictures of the sketches. Sketch the toughest, most complicated and most representative screens first. These will frequently determine the interaction model for most of the design.

4. Comp and Code

If you’re not doing the visual design yourself, collaborate with the graphic designer to iron out the details of the most representative screens and any other screens that require graphics. At the same time, collaborate with the developers to identify issues and areas for improvement throughout the process.

Forget the lengthy strategy documentation. Forget the deck of wireframes. Just short summaries (long enough to get the point across, but short enough to be able to do quickly), sketches and comps, limited to the things that need to be brought to a boil in Photoshop. Skimping on the deliverables can save a lot of time.

Untying Deliverables From Project Fees

Of course, sufficing with this shorter list of artifacts and untying deliverables from your fees require a change to the design process. In short, we need to shift the emphasis from documentation to collaboration.

Set the expectation from the beginning that you will work with stakeholders collaboratively. They will help you think through the design at every step. You will not be a wireframe monkey. Rather, you’ll focus on The Big Think. And you’ll do it together. If the client is unwilling or unable to spend time and energy on the design as you develop it, find another client. A client who is too busy to get involved in the process is a client who doesn’t care about their customers.

Collaboration is essential to great design. No one person can think of everything or always have the best ideas for every aspect of a product. It takes a group to make this happen. This might require you to occasionally browbeat the client into being available for frequent discussions on new and developing ideas, but the result will be infinitely better. And with the added input, you can focus less on stacks of deliverables and more on converting rough ideas into comps, prototypes and/or functioning pages that give undeniable weight to those ideas.

In practical terms, this means working closely and constantly with the visual designers and developers (assuming you’re not doing this work yourself). And it means frequently reviewing what’s being done and discussing at a deep level and at every step how to make improvements. It means talking through every detail and making sure someone has the job of being the resident skeptic, questioning every idea and decision in the interest of pushing the design further.

Break The Habit

By focusing on The Big Think, the deliverables will matter less. And for a designer, focusing on beautiful products is a whole lot more rewarding than dwelling on the step by step of deliverables. On your next time out, consider breaking the deliverables habit. Go from idea to code in as few steps as possible. Hefty amounts of collaboration can cure the sickly feeling that you’re an overpaid wireframer, empowering you to build designs that you know are killer work.

(al)

© Robert Hoekman Jr for Smashing Magazine, 2011.