When beginning writing plugins for WordPress, most developers will publish the fruits of their work in the official WordPress.org Plugin repository. It’s a great way to get into plugin development for your favorite CMS. I started this myself in June 2011 and so far it has gotten me lots of experience on how to code better and manage the whole process.

My Experience

If you’ve already published on WordPress.org or plan to do so, your plugin or theme is required to provide a so-called “readme.txt” text file. This is required because the repository parses it with Markdown language and draws all appropiate information from it, which is then displayed on the public repository. The header of that file also controls all aspects of the title, tagging, author, donate link etc. for your plugin or theme.

So, in this tutorial I’ll give you a lot of tips on how to do it the right way, based on my experiences over the last six months. I’ve seen so many great plugins in the repository but only a few have great descriptions and documentation. A lot of plugins have very minimal descriptions and documentation and leave the user alone. We want to change this.

All readme files are split into sections and the whole file is written using Markdown syntax.

The basic structure of a plugin’s readme.txt file intended for the WP.org repository looks like this:

Plugin HEADER Section

== Description ==

== Installation ==

== Frequently Asked Questions ==

== Screenshots ==

== Changelog ==

== Upgrade Notice ==

== Additional Info One (Optional) ==

== More Additional Info Two (Optional) ==

(Note: the last two sections are optional and will be combined into “Other Notes” later on the plugin page).

We are going to go through each section. As an example, I am using my bbPress Admin Bar Addition plugin.

Plugin Header Section

=== bbPress Admin Bar Addition ===
Contributors: daveshine
Donate link: http://genesisthemes.de/en/donate/
Tags: toolbar, adminbar, admin bar, bbpress, bbpress 2.0, administration, resources, links, forum, forum moderator, deckerweb
Requires at least: 3.1
Tested up to: 3.3.1
Stable tag: 1.3

This plugin adds useful admin links and resources for the bbPress 2.x Forum Plugin to the WordPress Toolbar / Admin Bar.

1. Obviously, the first line is the plugin’s full name – wrapped in the six equal signs. This should be the same as the title in your main plugin’s file header info. In converted form , this name will become your plugin’s URL (for example: wordpress.org/extend/plugins/bbpress-admin-bar-addition/) and also the forum tag for the WP.org support forum (for example: bbpress-admin-bar-addition – see forum for this tag/plugin). So please choose your plugin name wisely on what it does.
2. Contributers: Here put your WordPress.org username. This will be automatically linked to your profile. This is useful to showcase your plugin/theme portfolio and also for tracking your activity. As you will also answer support questions in the plugin’s forum there, your profile name will also appear there. So it’s really important that you use your username.
3. Donate link: This one is very clear. You could put any proper URL here. I always use a special donate page on my homepage. You can also place your PayPal donation URL here but please be warned that it could contain your email address and could become viewable by the public
4. Tags: Here you can list a few tags that fit with your plugin and its purpose. I’ve included some tags as you can see, including different spellings and each variation one might think of searching for. This is important, so your plugin can be found better through the repository’s search function, and for people who like browsing by tag. Also note that I’ve included the tag “deckerweb” at the end, which is the name of my company. This way I can filter all my plugins by tag to show to clients etc. It’s only a little tip but it could be very helpful.
5. Requires at least: The WordPress version that is the minimum requirement for your plugin. Really self-explanatory.
6. Tested up to: The latest WordPress version that you’ve tested your plugin with.
7. Stable tag: The current stable tag of your plugin – the latest available version you consider stable. This tag is important because it controls which version appears in the repository. (Be aware that this is controlled from the readme file of the trunk folder of your Subversion installation. You should first add and commit the version tags of your plugin via SVN and after that change the stable tag of your trunk readme file to the latest commited tag version.)
8. Header tagline: One sentence that sums up what your plugin does or why the user should need this particular one. Must be under 150 characters! All characters exceeding this limit will be cut off. This tagline is important because it will be displayed when searching the repository webseite and also when searching from your WP Admin dashboard under the “Plugins” menu. Again, choose this tagline wiseley and think of the users!

After the plugin header, the regular sections start. The section’s titles are used for the plugin menu you’ll see on the repository, these are: Description, Installation, FAQ, Screenshots, Other Notes, Changelog. There are more sections available, a somewhat hidden section called “Upgrade Notice” which could be controlled via the readme and also “Stats” and “Admin” which are fully controlled by WordPress.org!

Description Section

== Description ==
This small and lightweight plugin just adds a lot...
...

= Special Features =
...

Description should be clear and straight forward! Just include the full description/ documentation of what your plugin is doing, what are typical use cases, why the user should use it or what are advantages when using it.

Usually I include a lot of information in the description section because it will be seen first when users access your plugin page in the repository or view the info via a thickbox window in their WordPress backend. At the bottom of all my plugin’s description section I put feedback links (a link to my homepage contact form!), my social profiles and a link to my other WordPress plugins. I also include first instructions for translators who want to submit translations/ language packs for my plugins.

Note, that the title of the section is wrapped in double equal signs, this is for Markdown to catch the headlines/menu items later, so please don’t forget. Lots of paragraphs in your description can easily divided by blank lines. If you want to use sub headlines just put them in single equal signs like I’ve done with “= Special Features =”.

If you want orderered or unordered lists just use this syntax:
Ordererd List:

1. First item
2. Second item
3. etc.

Unordered List:

* First item
* Second item
* etc.

If you want a second unordered list in an unordered list use this, indent the appropriate items like so (note the indented items):

* First item
* Second item
 * Tird item (intended)
 * Fouth item (intended)
* Fifth item (regular)
* etc.

Italic text goes within asterisks, like so

*This will become italic*

Bold text goes within double asterisks, like so

**This will become some bold text**

URLs do not get parsed automatically, you have to put them between brackets, like so:

(https://pippinsplugins.com)

That will display the URL with the URL also used as linked text. If you want to change the link text just put this text into square brackets and add the URL in regular brackets, like so:

[Pippin's Plugins](https://pippinsplugins.com)

This will put out “Pippin’s Plugins” and linked to the given URL. Note: Link targets are not possible!

Important further notes: Affiliate links are not allowed in plugin readme files! Of course, all kinds of spam links etc. are also forbidden. The latter will get you banned from the repository immediately. With the affiliate links you might not get banned immediately but the plugin or your profile might be removed in the future. So please avoid this kind of stuff in the whole readme.txt file.

On to the next section:

Installation Section

== Installation ==

1. Upload the entire `bbpress-admin-bar-addition` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Look at your admin bar and enjoy using the new links there...
4. Go and manage your forum...

This section is pretty much self-explanatory but really important for a lot of users, especially beginners. It’s mostly done via an ordered list as you see in my example. Try to be as short and to the point. Have the user in mind who has not developed it but wants to use your plugin NOW.

Of course, after the list you can include text paragraphs or anything you want here.

Note, just see the backticks (`) on the first list element: these are usually used for code and file or folder names to make them more distinguishable from the rest. (Example: `/wp-content/plugins/`)

FAQ Section

== Frequently Asked Questions ==

= Does this plugin work with newest WP version and also older versions? =
Yes, this plugin works really fine with WordPress 3.3!
It also works great with WP 3.2 - and also should with WP 3.1 - but we only tested extensively with WP 3.3 and 3.2. So you always should run the latest WordPress version for a lot of reasons.

= How are new resources being added to the admin bar? =
Answer text...

Your users will have questions, mostly ones you haven’t thought of. So be prepared, they will come :-). A lot of plugin authors start here with an empy section and wait for the first “real” questions to arrive. This is absolutely ok if you’re doing it so! However, I usually decide to include some questions and answers from the day of release. In my opinion it’s more useful for the users to have as much information as possible right from the start. It’s a bit more imagination and writing work for the plugin author at the beginning but will definitely pay off in the long run!

See the single equal sings for the questions – these will become bold headlines! All the following text in the answer is added to this Q/A block. Then the next FAQ question (= headline) and answer and so on.

Next to the more visual part:

Screenshot Section

== Screenshots ==
1. bbPress Admin Bar Addition in default state (running with WordPress 3.3 here)
2. bbPress Admin Bar Addition in action - primary level (running with WordPress 3.3 here)
3. bbPress Admin Bar Addition in action - a secondary level (running with WordPress 3.3 here)

This one is pretty easy. Just include an ordererd list – this time a must – and be a little descriptive. That’s all – almost. You then have to include the actual screenshot image files. The names of the files are required like this: screenshot-1.png, sreenshot-2.png and so on. Please note: the graphic format is required to be in PNG!

The desciption of your ordered list elements will become the image caption for the screenshot. You can also use URLs here if you want.

Now, on to a more often changed section.

Changelog Section

== Changelog ==
= 1.3 =
* Added plugin support for...
* Minor code/ code documenation tweaks
* Updated readme.txt file - added new "Toolbar" wording introduced with WordPress 3.3
* Updated German translations and also the .pot file for all translators!
* Added banner image on WordPress.org for better plugin branding

= 1.2 =
* Added...
* Fixed...
* Updated...

This one seems also pretty self-explanatory, at least for me. Just put here a little development history of your plugin, what’s changed from version to version. I decided to include also smaller development steps so my users are fully informed about every little change but you have to decide for yourself how you will manage that.

The version goes again within single equal signs and should match your version tags used in Subversion and also in your readme and plugin file headers. All the changelog items go in an unordererd list – as this is the most appropiate format here (but you could also use text blocks if you really want…).

Well, now on to a somewhat hidden step:

Upgrade Notice Section

== Upgrade Notice ==
= 1.3 =
Added plugin support for 3 more third-party plugins. A few minor code/ documentation tweaks, updated readme.txt file and also updated .pot file for translators together with German translations.

= 1.2 =
Added plugin support

This section is not visable on the repository homepage but still really usefull. The content here will become visible once your users (admins, the ones with the fitting roles/ capabillities) get an update notice in their WordPress dashboard and then access their plugin’s listing page (wp-admin/plugins.php) or their update page (wp-admin/update-core.php). The users then see what’s changed in your new version. For that reason you should be short and descriptive here once again. Also the form of sentences or tags/keywords is highly recommended.

Finally, on to the last but still interesting section:

Other Notes Section

== Translations ==

* English - default, always included
* German: Deutsch - immer dabei!

*Note:* All my plugins are localized/ translateable by default. This is very important for all users worldwide. So please contribute your language to the plugin to make it even more useful. For translating I recommend the awesome ["Codestyling Localization" plugin](http://wordpress.org/extend/plugins/codestyling-localization/) and for validating the ["Poedit Editor"](http://www.poedit.net/).

== Additional Info ==
**Idea Behind / Philosophy:** Just a little leightweight plugin...

== Credits ==
* Thanx to [Dominik Schilling](http://wpgrafie.de/) [@ocean90](http://twitter.com/#!/ocean90) for great help with the CSS for the first level icon in WordPress 3.3!

Note: This section is fully optional and only included/parsed if you include more info marked with headlines in double equal signs! As you see in my example I use three such headlines at the bottom of my readme file, these will get summarized by the parser and all of these will appear under “Other Notes” (/other_notes/) on the plugin’s homepage in the repository.

You really have more freedom to include more documentation, translator info, additional info on the development of your plugin, credits, continued faq section, usage examples, more use cases — just endless potential here as you see. As I mentioned, this section is NOT required but I still recommend on adding these additional information sections. The reason is simple: I want the very best user experience for my users and so give them all information they might think of.

On some plugin pages in the repository I get frustrated because of how little information included. This leads me to not use the plugin, except when its functionality is a must. Otherwise, greatly described and documented plugins will show off a developer who cares for the users. …and hopefully also has his code well documented and maintained like the readme file. I guess you get the picture here 🙂

So, I hope you’ve got some useful information here for your plugin development and documentation. I am really curious to find more great plugins on the official repository and read some great documentation / user info there!

Check out the complete readme.txt file below:

=== bbPress Admin Bar Addition ===
Contributors: daveshine
Donate link: http://genesisthemes.de/en/donate/
Tags: toolbar, adminbar, admin bar, bbpress, bbpress 2.0, administration, resources, links, forum, forum moderator, deckerweb
Requires at least: 3.1
Tested up to: 3.3.1
Stable tag: 1.3
 
This plugin adds useful admin links and resources for the bbPress 2.x Forum Plugin to the WordPress Toolbar / Admin Bar.
 
== Description ==
 
This small and lightweight plugin just adds a lot bbPress 2.x related resources to your toolbar / admin bar. Also links to all setting/ tab pages of the plugin are added making life for forum administrators/ moderators a lot easier. So you might just switch from the fontend of your site to 'Topics' or 'Main Settings' page etc.
 
As the name suggests this plugin is intended towards forum admins/ webmasters and moderators. The new admin bar entries will only be displayed if the current user has the bbPress/ WordPress cabability of `moderate`. (Note: I am open for suggestions here if this should maybe changed to a more suitable cabability.)
 
= Plugin/ Theme Support =
*At this time the plugin out of the box supports also links to settings pages of some bbPress 2.x specific plugins:*
 
* Plugin: ["GD bbPress Attachments" (free, by Dev4Press)](http://wordpress.org/extend/plugins/gd-bbpress-attachments/)
* Plugin: ["bbPress Post Toolbar" (free, by Jason Schwarzenberger)](http://wordpress.org/extend/plugins/bbpress-post-toolbar/)
* Plugin: ["bbPress Antispam" (free, by Daniel Huesken)](http://wordpress.org/extend/plugins/bbpress-antispam/)
* Plugin: ["bbPress reCaptcha" (free, by Pippin Williamson)](http://wordpress.org/extend/plugins/bbpress-recaptcha/)
* Plugin: ["bbPress Moderation" (free, by Ian Haycox)](http://wordpress.org/extend/plugins/bbpressmoderation/)
* Plugin: ["bbPress2 BBCode" (free, by Anton Channing + bOingball + Viper007Bond)](http://wordpress.org/extend/plugins/bbpress-bbcode/)
* Plugin: ["bbPress2 Shortcode Whitelist" (free, by Anton Channing)](http://wordpress.org/extend/plugins/bbpress2-shortcode-whitelist/)
* Plugin: ["bbConverter" (free, by anointed + AWJunkies)](http://wordpress.org/extend/plugins/bbconverter/)
* Plugin: ["WP SyntaxHighlighter" (free, by redcocker)](http://wordpress.org/extend/plugins/wp-syntaxhighlighter/)
* *Your plugin/ theme? - [Just contact me with specific data](http://genesisthemes.de/en/contact/)*
 
= Special Features =
* Not only supporting official bbPress 2.x sites ALSO third-party and user links - so just the whole bbPress 2.x ecosystem :)
* Link to downloadable German language packs - only displayed when German locales are active (de_DE, de_AT, de_CH, de_LU)
* Link to official German bbPress forum - only displayed when German locales are active (de_DE, de_AT, de_CH, de_LU)
* *NOTE:* I would be happy to add more language/locale specific resources and more useful third-party links - just contact me!
 
= Localization =
* English (default) - always included
* German - always included
* .pot file (`bbpaba.pot`) for translators is also always included :)
* *Your translation? - [Just send it in](http://genesisthemes.de/en/contact/)*
 
Credit where credit is due: This plugin here is inspired and based on the work of Remkus de Vries @defries and his awesome "WooThemes Admin Bar Addition" plugin.
 
[A plugin from deckerweb.de and GenesisThemes](http://genesisthemes.de/en/)
 
= Feedback =
* I am open for your suggestions and feedback - Thank you for using or trying out one of my plugins!
* Drop me a line [@deckerweb](http://twitter.com/#!/deckerweb) on Twitter
* Follow me on [my Facebook page](http://www.facebook.com/deckerweb.service)
* Or follow me on [+David Decker](http://deckerweb.de/gplus) on Google Plus ;-)
 
= More =
* [Also see my other plugins](http://genesisthemes.de/en/wp-plugins/) or see [my WordPress.org profile page](http://profiles.wordpress.org/users/daveshine/)
* Tip: [*GenesisFinder* - Find then create. Your Genesis Framework Search Engine.](http://genesisfinder.com/)
 
== Installation ==
 
1. Upload the entire `bbpress-admin-bar-addition` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Look at your admin bar and enjoy using the new links there :)
4. Go and manage your forum :)
 
== Frequently Asked Questions ==
 
= Does this plugin work with newest WP version and also older versions? =
Yes, this plugin works really fine with WordPress 3.3!
It also works great with WP 3.2 - and also should with WP 3.1 - but we only tested extensively with WP 3.3 and 3.2. So you always should run the latest WordPress version for a lot of reasons.
 
= How are new resources being added to the admin bar? =
Just drop me a note on [my Twitter @deckerweb](http://twitter.com/deckerweb) or via my contact page and I'll add the link if it is useful for admins/ webmasters and the bbPress community.
 
= How could my plugin/extension or theme options page be added to the admin bar links? =
This is possible of course and highly welcomed! Just drop me a note on [my Twitter @deckerweb](http://twitter.com/deckerweb) or via my contact page and we sort out the details!
Particularly, I need the admin url for the primary options page (like so `wp-admin/admin.php?page=foo`) - this is relevant for both, plugins and themes. For themes then I also need the correct name defined in the stylesheet (like so `Footheme`) and the correct folder name (like so `footheme-folder`) because this would be the template name when using with child themes. (I don't own all the premium stuff myself yet so you're more than welcomed to help me out with these things. Thank you!)
 
= There are still some other plugins for bbPress 2.x out there why aren't these included by default? =
Simple answer: The settings of these add-ons are added directly to the bbPress main settings page and have no anchor to link to. So linking/ adding is just not possible.
 
== Screenshots ==
 
1. bbPress Admin Bar Addition in default state (running with WordPress 3.3 here)
2. bbPress Admin Bar Addition in action - primary level (running with WordPress 3.3 here)
3. bbPress Admin Bar Addition in action - a secondary level (running with WordPress 3.3 here)
 
== Changelog ==
 
= 1.3 =
* Added plugin support for "bbPress Antispam" (free, by Daniel Huesken)
* Added plugin support for "bbPress Moderation" (free, by Ian Haycox)
* Added plugin support for "WP SyntaxHighlighter" (free, by redcocker)
* Minor code/ code documenation tweaks
* Updated readme.txt file - added new "Toolbar" wording introduced with WordPress 3.3 (formerly known as the Admin Bar)
* Updated German translations and also the .pot file for all translators!
* Added banner image on WordPress.org for better plugin branding :)
 
= 1.2 =
* Added plugin support for "bbConverter" (free, by anointed + AWJunkies)
* Added new external resource - "Hooks, Filters and Components for bbPress 2.0" at etivite.com
* Added new external resource - "Getting Started with bbPress" by Smashing Magazine
* Fixed display of first-level icon on mouse-hover with WordPress 3.3 - props to [Dominik Schilling](http://wpgrafie.de/) [@ocean90](http://twitter.com/#!/ocean90) for great help with the CSS!
* Updated the screenshots with fixed first-level icon
* Updated and improved readme.txt file
* Updated German translations and also the .pot file for all translators!
* Now I'd call this some fully optimized release - enjoy :-)
 
= 1.1 =
* Added link to topic tag "bbpress-plugin" in the official bbPress Forum
* Corrected a wrong link (free WP.org forum)
* Minor code tweaks
* Fixed some ugly typos (Mmh, happens sometimes...)
* Updated German translations and also the .pot file for all translators!
 
= 1.0 =
* Initial release
 
== Upgrade Notice ==
 
= 1.3 =
Added plugin support for 3 more third-party plugins. A few minor code/ documentation tweaks, updated readme.txt file and also updated .pot file for translators together with German translations.
 
= 1.2 =
Added plugin support for bbConverter as well as 2 new resources. Fixed first-level icon display in WP 3.3. Updated readme.txt file, screenshots and also .pot file for translators together with German translations.
 
= 1.1 =
Added link to topic tag "bbpress-plugin" in official forum. Corrected a wrong link and added minor code tweaks, also fixed some ugly typos. Updated .pot file for translators and German translations.
 
= 1.0 =
Just released into the wild.
 
== Translations ==
 
* English - default, always included
* German: Deutsch - immer dabei! [Download auch via deckerweb.de](http://deckerweb.de/material/sprachdateien/bbpress-forum/#bbpress-admin-bar-addition)
 
*Note:* All my plugins are localized/ translateable by default. This is very important for all users worldwide. So please contribute your language to the plugin to make it even more useful. For translating I recommend the awesome ["Codestyling Localization" plugin](http://wordpress.org/extend/plugins/codestyling-localization/) and for validating the ["Poedit Editor"](http://www.poedit.net/).
 
== Additional Info ==
**Idea Behind / Philosophy:** Just a little leightweight plugin for all the bbPress Forum managers out there to make their daily forum admin life a bit easier. I'll try to add more plugin/theme support if it makes some sense. So stay tuned :).
 
== Credits ==
* Thanx to [Dominik Schilling](http://wpgrafie.de/) [@ocean90](http://twitter.com/#!/ocean90) for great help with the CSS for the first level icon in WordPress 3.3!