The key is to think about your customer
I’m engaged in the creation of at least 3 open source software projects at Georgia Tech. Presently, these products are quite powerful for us, but hard for others to use. I’m pushing my students to create great releases — but they may not know what I’m looking for.
Here’s an outline for how I think it should be done. This is targeted for a university research group that is interested to get its code out there. Not all of these choices will be appropriate in other settings.
What do YOU look for in a software release?
When you download software from the web, what do you want to see? Keep that thought on your mind you as you create (or contribute to) a source code release. Always be thinking about that customer who is downloading your code as you create a release.
Source code releases are quite different from fully-baked software products. The way customers use them is much different — you’re creating an environment for them to work in, not just a program for them to run. In many ways it is tougher to produce a source code release than to distribute a program.
Here are the main things people are looking for:
- Easy download and install;
- Simple example they can run;
- Easily navigable directory structure;
- Useful comments in the code.
Probably other things too, but those are at the top of my list. For brevity, the rest of this post is going to be rather prescriptive (how I want our students to set up our releases). Sorry for that. But if you have opinions on the matter, please post them as comments. You may change our minds.
Guarantee it’ll work on a base platform (OS + hardware)
By that I mean, don’t try to make everybody happy. Choose a combination of OS and computing hardware that facilitates your work and your development. Make sure your code always works there.
If your customers really need or want your code to work, it is probably easier for them to reproduce that home environment than it would be for you to make the code work on a different environment. If you have the resources, you can later ensure the code works on other platforms, but this can be expensive.
While we’re on this point, let me encourage you to consider ubuntu (or other linux) as the home platform for your work. Here’s why: You can almost always port working code from linux to Windows and Mac OSX, but it is often a challenge to port from Windows to other operating environments.
subversion for versioning AND distribution
It is impossible to do serious collaborative work on code without subversion, or something similar. I really like subversion for use as a source code repository because the commands are simple and it is well known and tested. Many ISPs (such as dreamhost) can provide easily configurable subversion servers.
Finally, you can make your release on subversion publicly readable, and therefore use that channel to allow folks to download the code easily.
I hear that git is good too. I don’t know much about it. I use subversion because I know it already and don’t see a need to change.
The release IS the website
What does that mean?
What I mean is that the directory structure of your source code should include html files throughout — one index.html file in each directory. Then voila these html files are the code for your website.
In addition to relevant content, the html in each directory should have obvious navigation links down to the subdirectories, and up to parent directories. It is also good to have a link back to the main page in all web pages. By the way, these links should be coded as relative links (not hardcoded to specific directory locations!)
If you follow this approach, your source code directory structure mirrors your website structure, and both are now easily navigable.
When you make code revisions, the index.html files can be conveniently edited to reflect the changes. And once you’re all done, just check it in.
To “distribute” your new release just copy your code tree to your website hosting location (I use rsync for this purpose).
Using a wiki for documentation
For one of our projects we’re using a wiki as the main documentation structure rather than the index.html files in the source code tree. The idea is that adding useful content to the wiki documentation is much easier than editing the html files.
In this case, I advise still to keep the index.html files around, but keep the content sparse, and have them point to the relevant wiki pages. The wiki documentation organization should also follow the directory tree structure.
The directory structure should follow common conventions so experienced coders will be familiar with it and find it more usable. A clean directory structure really helps provide a “clean” and “fun” out of the box experience for your customers.
Here are some recommended directory structures (# indicates a comment). This first example is a structure one might use for a software library or API:
/... # the root of the directory tree /App1 # important application that is part of release /App2 /Bin # scripts and very small helper apps /Core # common or core source code goes here /Docs # documentation lives here /Examples # example applications built using your API /example-applicationA /example-applicationB /Lib # compiled libraries land here
Some prefer /Src as an alternative name for /Core.
Other languages or other uses might might call for a different structure. Python for instance doesn’t use the concept of “/Lib” in the same way C/C++ does. Here’s an alternative structure that might work better for Python:
/... # the root of the directory tree /app1 # important app that's part of release /app2 /Bin # scripts and very small helper apps /Docs # documentation lives here /Examples # example applications built using your API /example-applicationA /example-applicationB /module1 /module2
How to help your users configure their installation
There are many ways to do this, some of them are fancy and automatic. My recommendation though is to use a simple configuration file that sets environmental variables for your user. Call this file “config.sh” and place it in the /Bin directory.
Customers should be advised, after they unpack the distribution, to edit this file to change relevant or important directory locations for their machine. They should also “source” this file before each session.
Source code documentation
Depending on the language you’re writing in, use a tool like javadoc, epydoc or doxygen (for Java, Python and C++ respectively). These tools parse your source code, looking for specific comments. They then automatically generate html documentation for your code.
Point the documentation generator to the /Docs subdirectory for output. The /Docs subdirectory is then the root for API documentation.
Content of the top page on the website
The main page should include the following items:
- Brief overview of what the software does. Describe unique features, or why it is different from other packages. If the text gets too long, crop it and point to another page for details.
- Platforms it will work on. Describe hardware and software requirements.
- How do download and install. If it is complicated, create and point to a separate page.
- How to get a simple example running. Hold their hands on this so they get a good feeling.
- Short overviews of major components and/or apps, along with links to their respective subpages.
- Link to top of API documentation tree.
- Link to more detailed tutorial.
Phew, I think that’s it for now.