How To Improve Your WordPress Plugin’s Readme.txt

Advertisement

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?

readmeheader1

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:

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

Markdown7 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 Connect108:

Simple Twitter Connect's listing in the plugin directory
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
Simple Twitter Connect’s readme file in Notepad.

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

Simple Twitter Connect's listing on the Edit plugin page in the WordPress dashboard
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-markdown9. 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.

Syntax Example Outputs as Use for
=== foo === === Plugin Name === <h2>Plugin Name</h2> Plugin name
== foo == ==Description== <h3>Description</h3> Tabbed section headings
= foo = =Inline heading= <h4>Inline heading</h4> Headings in the body of the readme
* foo * list item, *list item <ul>
<li>list item</li>
<li>list item</li>
</ul>
Unordered list
1. foo, 2. foo 1. list item, 2. list item <ol>
<li>list item</li>
<li>list item</li>
</ol>
Ordered list
foo bar You talking to me? <blockquote>You talking to me?</blockquote> block quotes
*foo* *emphasis* <em>emphasis</em> Italics
**foo** **bold** <strong>bold</strong> Bold
‘foo’ ‘wp-config.php’ wp-config.php Any code you want to display (including shortcodes)
[link] (http://foobar.com “foobar”) [WordPress](http://wordpress.org/ “Your favorite software”) <a href=”http://wordpress.org/” title=”Your favorite software”>WordPress</a> Links
<http://foobar.com> <http://wordpress.org> <a href=”http://wordpress.org”>

http://wordpress.org</a>

Links
[youtube http://foobarvideo.com] [youtube http://www.youtube.com/watch?v=CVmGBoPx6Ms] <div class=’video’><object width=’532′ height=’325′><param name=’movie’ value=’http://www.youtube.com/v/ CVmGBoPx6Ms?fs=1′></param> <param name=’allowFullScreen’ value=’true’></param><param name=’allowscriptaccess’ value=’never’></param><embed src=’http://www.youtube.com/v/ CVmGBoPx6Ms?fs=1′ type=’application/ x-shockwave-flash’ allowscriptaccess=’never’ allowfullscreen=’true’ width=’532′ height=’325′></embed></object></div> Video

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 Connect108, 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.

the plugin header information in use in the plugin directory

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.
    Contributor tag in the plugin directory linked to the contributor's page
    A contributor tag done right.
    plugin author listed in the directory that isn't a WP.org username
    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.
    The WordPress.org listings for the twitter tag showing facebook plugins and an image gallery plugin
    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 WordPress11. 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.

Simple Twitter Connect's short description on the WordPress dashboard plugin page

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

Simple Twitter Connect's short description on the WordPress dashboard plugin page

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:

buddystream on the listings page without adequate short decription

A plugin short description written in chinese

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

This short description drops down over four lines

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 Blocker12:

Plugin's short description cut off mid-sentence

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

  • VideoPress13
    “Manage and embed videos hosted on VideoPress. Requires a WordPress.com blog with the VideoPress premium upgrade.”
  • Yet Another Related Posts Plugin14
    “Display a list of related entries on your site and feeds based on a unique algorithm. Templating allows customization of the display.”
  • BuddyPress15
    “Social networking in a box. Build a social network for your company, school, sports team or niche community.”
  • The Google+ Button16
    “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:

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:

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 lousy22. In fact, some plugins, even popular ones23, 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 Connect24. 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:

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”

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.

Update WP Touch notice
This user needs to update WP Touch!

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

WP touch's changelog
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 Connect37 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.
  • The changelog must have the most recent changes first.

Upgrade Notice

The upgrade notice gives additional information to users who are about to upgrade. Although this doesn’t appear in the WordPress plugin directory it’s fed through to users on the WordPress Dashboard appearing both on wp-admin/update-core.php. Here’s the upgrade notices for BuddyPress and Akismet in action:
buddypress upgrade notice for 1.5.3
This section is really helpful as it gives a user additional information they can use before they upgrade.

Tips for Writing Upgrade Notices

  • keep your upgrade notices short and descriptive. Aim to be informative.

Bonus – Adding a Banner Image

Since this article was published, WordPress have made it even easier for your to show off your plugin in the WordPress plugin directory. Matt announced that he had been looking for ways to give plugin authors more control over their plugin page on the directory38. The first step was introducing banner images for plugin pages. Check out the banner image on Hello Dolly39.

Note: WordPress.org are still experimenting with plugin pages so these may change.

To add a banner image to your plugin page:

  • Create a 772 x 250 pixel jpg or png (no GIFs)
  • Check it in to your plugin’s SVN directory with the path assets/banner-772x250.(jpg|png). Note:  the assets directory is added to your plugin’s root directory, not the trunk
  • your banner image will appear on the next plugin directory refresh (happens every 15 minutes).

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:

(al)

Footnotes

  1. 1 http://www.smashingmagazine.com/2011/11/23/improve-wordpress-plugins-readme-txt/
  2. 2 http://wordpress.org/extend/plugins/contact-form-plugin/
  3. 3 http://wordpress.org/extend/plugins/wordpress-tiniest-super-cache/
  4. 4 http://wordpress.org/extend/plugins/profitshare/
  5. 5 http://wordpress.org/extend/plugins/lite-cache/
  6. 6 http://wordpress.org/extend/plugins/tahir-demo-plugin/
  7. 7 http://daringfireball.net/projects/markdown/
  8. 8 http://wordpress.org/extend/plugins/simple-twitter-connect/
  9. 9 http://markjaquith.wordpress.com/2007/03/16/plugin-directory/
  10. 10 http://wordpress.org/extend/plugins/simple-twitter-connect/
  11. 11 http://wordpress.org/extend/plugins/about/readme.txt
  12. 12 http://wordpress.org/extend/plugins/simple-trackback-validation-with-topsy-blocker/
  13. 13 http://wordpress.org/extend/plugins/video/
  14. 14 http://wordpress.org/extend/plugins/yet-another-related-posts-plugin/
  15. 15 http://wordpress.org/extend/plugins/buddypress/
  16. 16 http://wordpress.org/extend/plugins/google/
  17. 17 http://wordpress.org/extend/plugins/eg-attachments/
  18. 18 http://wordpress.org/extend/plugins/wordpress-google-maps/
  19. 19 http://wordpress.org/extend/plugins/nextgen-gallery/
  20. 20 http://wordpress.org/extend/plugins/wp-super-cache/installation/
  21. 21 http://wordpress.org/extend/plugins/wordpress-mu-domain-mapping/installation/
  22. 22 http://wordpress.org/extend/plugins/flexo-facebook-manager/faq/
  23. 23 http://wordpress.org/extend/plugins/network-publisher/
  24. 24 http://wordpress.org/extend/plugins/simple-twitter-connect/screenshots/
  25. 25 http://wordpress.org/extend/plugins/social-profiles-sidebar-widget/screenshots/
  26. 26 http://wordpress.org/extend/plugins/wp-pagenavi/screenshots/
  27. 27 http://wordpress.org/extend/plugins/nextgen-gallery/screenshots/
  28. 28 http://wordpress.org/extend/plugins/nextgen-gallery/other_notes/
  29. 29 http://wordpress.org/extend/plugins/comment-rating/other_notes/
  30. 30 http://wordpress.org/extend/plugins/yet-another-related-posts-plugin/other_notes/
  31. 31 http://wordpress.org/extend/plugins/wordpress-importer/other_notes/
  32. 32 http://wordpress.org/extend/plugins/add-link-to-facebook/other_notes/
  33. 33 http://wordpress.org/extend/plugins/jw-player-plugin-for-wordpress/other_notes/
  34. 34 http://wordpress.org/extend/plugins/xhanch-my-twitter/other_notes/
  35. 35 http://wordpress.org/extend/plugins/wordbooker/other_notes/
  36. 36 http://wordpress.org/extend/plugins/seo-automatic-links/other_notes/
  37. 37 http://wordpress.org/extend/plugins/simple-twitter-connect/changelog/
  38. 38 http://wpdevel.wordpress.com/2011/12/21/been-giving-a-lot-of-thought-to-how/
  39. 39 http://wordpress.org/extend/plugins/hello-dolly/
  40. 40 http://wordpress.org/extend/plugins/about/readme.txt
  41. 41 http://wordpress.org/extend/plugins/about/validator/
  42. 42 http://sudarmuthu.com/wordpress/wp-readme
  43. 43 http://wp.tutsplus.com/tutorials/how-to-publish-to-the-wordpress-plugin-repository/
  44. 44 http://wpmu.org/how-to-write-a-wordpress-plugin-12-essential-guides-and-resources/

↑ Back to topShare on Twitter

Siobhan McKeown is a big fan of words, and of WordPress, which works out pretty well since she runs Words for WP, the only copywriting service dedicated to WordPress service providers. You can find her on her personal blog, twitter and occasionally hanging out on G+.

Advertising

Note: Our rating-system has caused errors, so it's disabled at the moment. It will be back the moment the problem has been resolved. We're very sorry. Happy Holidays!

  1. 1

    That’s a brilliant article. Very very well laid down and nicely explained. Kudos Siobhan!

    //Wasseem

  2. 2

    Excellent article and a must read for all plugin developers I must say. One thing I would like to add to tips about changelog. Many plugin authors write changelog starting from first version at the top and the latest version at the bottom. This makes reading changelogs very cumbersome. Hope people understand this and always mention the latest version at the top. Would save some precious time.

    • 3

      I agree for large plugins or those with an extensive changelog history, it should be archived at the project site, but I also think it’s pretty helpful to include the last several sets of changelogs in case someone is upgrading a few versions at a time or wants to see the recent revision history. Maybe the last 5 or 6 releases at a minimum.

    • 4

      Yeah, that’s a good point. I hate having to scroll down to the bottom!

  3. 5

    Great article, Siobhan, this stuff often gets too neglected by plugin authors, especially those starting out. This is a great reference article on how to get it done right. Bookmarked! :)

  4. 6

    My readme file is sorely lacking. After reading this I’ve got some work to so.

    Thanks for a great read!

  5. 7

    Great article.Thank you.

  6. 8

    I would like to see a little information about Upgrade section. It’s not very well documented and is required by the WP readme.txt Validator.

  7. 11

    I loved your article, but I also love the font you used in the first picture, I could what the name of the font?

    thanks

  8. 12

    Nice article.Thank to share

  9. 13

    IMO the biggest problem is, that those things are not controlled during upload/publishing, or that there is no wizard implemented on wp.org. It should control also other things: errors with wp_config on, usage of obsolete functions, using of bad way – own db connect, unsecure functions, not using translations etc.

  10. 14

    Wow, an excellent and helpful article. I wish I’d read this before I posted my first plugin to the repository.

  11. 15

    Erlend Sogge Heggen

    November 29, 2011 12:33 pm

    Immensely important article. I can’t tell you how many plugins I’ve decided not to download purely on the basis of a lacking readme.txt, especially a missing changelog.

    This should go into the official WordPress Codex.

  12. 16

    Good article, and I like your choice of examples. ;)

    Some points of note:

    – Author URI and Plugin URI from the readme.txt are not used anywhere. Including them is nice, but doesn’t actually matter too much. The ones in the plugin’s actual PHP file are read and used though.

    – The Plugin URI in the plugin’s PHP file is *critical*. It should be unique and specific to the plugin, and preferably on a domain that you control. The plugin URI actually plays a pivotal role in the upgrade system, so use it well.

    – Stable Tag points to a directory in the SVN /tags directory. So Stable Tag: 0.15 means that the stable version of the plugin is in /tags/0.15. The actual version displayed in the download link comes from the version number in the plugin’s PHP file itself, which is in that directory. This sometimes confuses people. Remember to check both your plugin file *and* the readme.

    – If you use a Stable Tag that isn’t trunk, then *everything else* is read from that /tags directory. However, /trunk should still contain a complete copy of the “development” version of the plugin. This can be the beta of the next version, for example. It’s your “in-progress” code.

    – Per the guidelines, if you make an update to a plugin with a Stable Tag of trunk, you must bump the version number as well. Therefore, we highly recommend the /tags system for plugins that are undergoing lots of small changes. We tend to ignore this for new plugins for a while, until they stabilize, but we do want to enforce this. If you’re changing things out from under your users and not bumping the version, then they won’t know anything changed.

    – The description displayed in the Plugins listing on the WP admin screens comes from the Description in the plugin’s PHP file itself. WordPress does not read or parse the readme.txt file in any way. Only WordPress.org does that, at present.

    – “Contributors” should always be all wordpress.org usernames, and it has nothing whatsoever to do with “Committers”, who are the people who have access to update the plugin. People sometimes get this confused.

    – Links in your readme.txt is fine, but all links should be relevant. No ad-spam, no sponsored links. This will get your plugin booted from the repository.

    – Changelogs *MUST* be most-recent-changes=first. If you do it backwards, then you’re doing-it-wrong. Changelogs are useful for more than just display on the site, and may be used for more in the future. Look at the template, and get this crucial and vital section right. Use the * prefixes. Things like that. Even major plugin authors are doing this wrong, and we’re griping at them continually about it. We want it that way *for a reason*.

  13. 17

    Covers everything with regards to Readme.txt file. Thank you so much.

  14. 18

    How do you add a little TM (trademark) logo in the readme.txt ?

  15. 20

    Just a couple of days ago, I was working on a compilation of productivity plugins for WordPress. I noticed that many plugin authors name their plugins so poorly that they become hard to find, or users simply skip them in the search due to ambiguous titles.

  16. 21

    Really useful post actually, thanks. Wish more WordPress developers would take note of this as it’s really helpful for the end user.

  17. 22

    Gabriel Hautclocq

    January 31, 2012 8:41 am

    Thank you for this article. It motivated me to update the readme.txt of Counterize, which is much more readable by humans now. And I learned useful things :)

  18. 23

    One thing I could not find in this is how to get the background image on plugins page, many plugins have it and that’s what I have been searching for a long time now.

  19. 24

    Wow awesome article, this was so worth the long read.

    I think the readme file is great to promote your free plugin to get more downloads. In the end you could promote a premium version from within your free plugin.

    Thanks for this superb article.

  20. 25

    Nice Article
    I fount one nice plugin to generate readme file for plugin
    ReadMe Creator : http://wordpress.org/extend/plugins/readme-creator/

  21. 26

    GOSense – Responsive Adsense Magazine WP Theme
    is nice you should check it if you want easy seo on your wp theme.

    http://www.youtube.com/watch?v=2ZL8JYjZ1mM&feature=youtu.
    be
    my web blog :: [GOSense – Responsive Adsense Magazine WP Theme](http://www.youtube.com/watch?v=2ZL8JYjZ1mM&feature=youtu.be “+txt+”)

  22. 27

    I’m really loving the theme/design of your web site. Do you ever run into any internet browser compatibility issues? A couple of my blog readers have complained about my website not operating correctly in Explorer but looks great in Firefox. Do you have any recommendations to help fix this issue?

  23. 28

    Quality content is the important to interest the
    visitors to pay a quick visit the web page, that’s what this site is providing.

  24. 29

    Great article!
    After reading this Q&A, http://wordpress.stackexchange.com/q/25636/12615, and searching for “readme.txt” articles, arrived here.

    And from that technique, which works flawlessly, I think documenting “Text Domain” and “Domain Path” would be a plus :)

  25. 30

    Thanks in favor of sharing such a fastidious idea, post is pleasant, thats
    why i have read it fully

    Feel free to surf to my webpage: [Annette](http://forum.trapexit.org/profile.php?mode=viewprofile&u=4012 “Best Web Hosting”)

  26. 31

    Attractive section of content. I just stumbled upon your weblog and in accession capital to
    assert that I get actually enjoyed account your blog posts.
    Any way I will be subscribing to your augment and even I achievement you access consistently
    fast.

    Look into my webpage: [golfing odds](http://betongolfsystem.com “golfing odds”)

  27. 32

    Hurrah! After all I got a weblog from where I know how to really take
    valuable data regarding my study and knowledge.

    my site; [Frederic](http://blockpornkidsafe.com/ “parental control software proxy”)

  28. 33

    Hello,
    I was contemplating adding a backlink back to your website since
    both of our sites are based mostly around the same topic.

    Would you prefer I link to you using your website address:
    http://wp.smashingmagazine.com/2011/11/23/improve-wordpress-plugins-readme-txt/ or website title:
    How To Improve Your WordPress Plugin’s Readme.txt | Smashing WordPress. Please let me know! Thanks!

    My webpage :: [http://QROPSPension.co.za/](http://QROPSPension.co.za “QROPS”)

  29. 34

    I am sure this post has touched all the internet visitors, its really really good paragraph on building
    up new webpage.

  30. 35

    This article presents clear idea designed for the new
    people of blogging, that actually how to do running a
    blog.

    Also visit my blog – (vueloschina.com)

  31. 36

    Appreciating the time and energy you put into your site
    and detailed information you provide. It’s great to come across a blog every once in a while that isn’t
    the same outdated rehashed material. Fantastic read!
    I’ve saved your site and I’m including your RSS feeds to my Google account.

    Check out my page [Wilda](http://fromearth.wildeklasse.
    de/?p=674 “Wilda”)

  32. 37

    With havin so much written content do you ever run into any problems of plagorism or copyright violation?
    My site has a lot of exclusive content I’ve either authored myself or outsourced but it appears a lot of it is popping it up all over the web without my permission. Do you know any techniques to help prevent content from being ripped off? I’d truly appreciate it.

    My website; [anti cellulite Kneipp](http://cellulitesmoothing.
    com “anti cellulite Kneipp”)

  33. 38

    Great post.

    Here is my webpage; [mole removal london cheap](http://wartsdestroyer.
    com “mole removal london cheap”)

  34. 39

    Wonderful beat ! I would like to apprentice while you amend your web site, how could i subscribe for a blog site?
    The account aided me a acceptable deal. I had been tiny bit acquainted of this your broadcast provided
    bright clear idea

    My blog [diet for diabetes type 2 patients](http://organicdiabetesreversal.
    com “diet for diabetes type 2 patients”)

  35. 40

    It is in point of fact a great and helpful piece of info.
    I am happy that you just shared this helpful information with us.
    Please stay us informed like this. Thank you for sharing.

    My page: [laanpengenu.info](http://www.webcrawler.com/info.
    wbcrwl.301.1/search/web?q=rosenrodvirkning.blogspot.

    com&qs=Relevance&fcoid=107&fcop=right&fpid=2&qlnk=True “laanpengenu.info”)

  36. 41

    I think that what you published was very logical. But, what about
    this? what if you composed a catchier post title? I mean, I don’t want to tell you how to run your blog, however what if you added something to possibly grab folk’s attention?
    I mean How To Improve Your WordPress Plugin’s Readme.txt | Smashing WordPress is kinda plain. You should glance at Yahoo’s home page and see
    how they create post headlines to get people to
    open the links. You might try adding a video or
    a related picture or two to get people interested about everything’ve written. In my opinion, it could make your posts a little bit more interesting.

    Also visit my blog … [products to lighten melasma](http://lightenyourskintoday.com “products to lighten melasma”)

  37. 42

    Hi my friend! I wish to say that this post is amazing, great written and come with approximately all
    important infos. I’d like to peer more posts like this .

    My web-site :: [organic](http://www.wholesale-n-closeout.com “organic”)

  38. 43

    I do agree with all the ideas you’ve presented to your post. They’re very convincing
    and will certainly work. Nonetheless, the posts are very short for beginners.
    Could you please prolong them a little from subsequent time?
    Thanks for the post.

    Feel free to visit my page: [dubturbo](http://www.youtube.

    com/watch?v=VS0aKc9kVLo “dubturbo”)

  39. 44

    I’m really enjoying the design and layout of your site. It’s
    a very easy on the eyes which makes it much more pleasant
    for me to come here and visit more often. Did you hire out
    a designer to create your theme? Superb work!

    Here is my site [incoming links checker](http://google-backlink-checker.
    tumblr.com/ “incoming links checker”)

  40. 45

    Do you mind if I quote a few of your articles as long as I
    provide credit and sources back to your webpage? My blog
    is in the very same area of interest as yours and my visitors would
    truly benefit from some of the information you provide here.
    Please let me know if this okay with you. Thank you!

    My site :: [Indo China Travel](http://Faroriental.Tblog.
    com/ “Indo China Travel”)

  41. 46

    Hello, yup this post is genuinely nice and I have learned lot
    of things from it regarding blogging. thanks.

    Here is my site – [allegedly beat and kidnapped girlfriend](https:
    //gmargari.wordpress.com/2008/07/14/kurt-cobain-ghost/ “allegedly beat and kidnapped girlfriend”)

  42. 47

    Write more, thats all I have to say. Literally, it seems
    as though you relied on the video to make your point.
    You clearly know what youre talking about, why waste your intelligence on just posting videos to your weblog when you could be giving us something enlightening to read?

    Also visit my website: [seo company](http://judiahagthrop.
    com/privacy “seo company”)

  43. 48

    Good article! We are linking to this particularly great post on our site.
    Keep up the good writing.

    Look into my webpage [Chase](%url% “Chase”)

  44. 49

    Very good info. Lucky me I ran across your website by accident (stumbleupon).

    I’ve book marked it for later!

    Stop by my weblog :: [wartrol](%url% “wartrol”)

  45. 50

    What a fantastic tutorial. Thank you!

  46. 51

    another plugin readme.txt generator:

    http://GenerateWP.com/plugin-readme/

  47. 52

    Great tips and to do list for organically getting more downloads through a better copy on the plugin page. Will definitely try to get all these done!
    Thank you for a detailed article!

↑ Back to top