I’ve been creating Redmine and ChiliProject plugins since 2007 and over that time I’ve been refining the documentation I include in each and every plugin. Documentation is tough. You need to provide enough documentation so someone can install and use your plugins (legally) but keep it short enough so that people will actually read it.

I’ve settled on four main files for my documentation:

1. GPL.txt
2. COPYRIGHT.txt
3. CREDITS.txt
4. README.rdoc

GPL.txt

Since both Redmine and ChiliProject are released under the GNU GPLv2 then it’s best to release plugins under the same license. In order to fulfill the GPL, I bundle a copy of the license with each and every plugin.

COPYRIGHT.txt

The COPYRIGHT.txt file works with the GPL.txt to establish who owns the copyright of the plugin. It includes a short description of the plugin, the copyright owner, the copyright date, and the brief license snippet for the GPL.

PLUGIN DESCRIPTION

Copyright (C) 2011 Eric Davis

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

CREDITS.txt

The CREDITS.txt file lists all of the people involved in creating the project and any major third party resources for it. This is where I list the plugin maintainer, major contributors, and any project sponsors (for paid plugin commissions). Since switching to git a few years ago I haven’t used this file for all contributors because git keeps track of contributors but it’s still nice to document who is the maintainer. Especially with how often code is forked on Github now.

Thanks go to the following people for patches and contributions:

* Eric Davis – Maintainer
* John Doe – Query optimization
* Karl Maxwell – Translations

README.rdoc

Here is where the bulk of the documentation is stored. The README file is the one file that every user (should) read before installing the plugin. I separate my README files into a few sections so it’s easier to scan (especially once you use a few of my plugins and understand the format).

Plugin description

Here I describe what the plugin does for the user. By the time you finish reading this section you should know if you are interested in the plugin or if you want to look for a different one.

Features

I make a list of the major features of each plugin here. Typically I try to keep the list to the top 10 most important features. Sometimes the plugin is so simple that I include the features in the plugin description.

Getting the plugin

This short section is used to link to the authoritative urls for the plugin. Since it’s easy to have forks and different versions of code now, this makes sure that the code is downloaded from the official site (or that the user knows they are using a different version).

Installation and Setup

The installation section documents if there are any special installation or set up steps. Commonly I’ll list what Ruby gems will need to be installed and where to configure the plugin.

Usage

I use the usage section to document … well… how the plugin is used. I’ll explain how the features work, what automation scripts are included (rake), and if there is a specific work-flow the plugin uses. On some of my larger plugins I’ve documented the different use cases the plugin solves.

License

To be 100% complete, I also include a short snippet describing the plugin license and referring to the main license file (GPL.txt).

Project help

Finally, in the last section I have instructions on how to get help with the plugin or where bugs should be reported. For 95% of my plugins that would be the Little Stream Software ChiliProject but on occasion a different system will be listed.

So that’s a quick tour of the documentation I include in every one of my plugins. If you create a plugin; at a minimum make sure you have a README file and a license file. Without those two files, people won’t know how to use your plugin (README) and won’t be legally allowed to use it (the license).

All of my documentation templates are available as part of my redmine_plugin_tasks project. Though I haven’t announced it here yet, I’ve been using these scripts since 2009 to automate a bunch of my plugin development.