Archive for September, 2006

How to write a book.

Saturday, September 30th, 2006

I'm not done the book yet, so this blog may be a little premature. Still, I've learned a lot from what I've written so far. The main one is that the hardest part of the book is simply finding the time to write it.

The next hardest part is figuring out how to organize it. But I've solved that problem, I think. My solution is to concentrate on writing the contents first, even if that means the drafts look like a random collection of notes. As the notes get fleshed out into paragraphs, sections, and chapters, the organization grows naturally.

As of this writing, I'm up to 60 pages, and I have only about 5 pages that are specific to FreeRADIUS. Just explaining the concepts behind RADIUS, and correcting common misconceptions is taking a fair amount of space. That's good, though. It means that that the rest of the book is built on those foundations, and isn't just a jumble of “how-to's”.

The finished book will have a number of “how-to's”, of course. But without the additional background materials, they help people copy configurations, which is not the same as helping them to solve problems.

Why the server succeeded.

Saturday, September 2nd, 2006

When I started FreeRADIUS, there were a few open source RADIUS servers in development. Yet a few years later, almost all of them are not actively developed or maintained. What qualities did FreeRADIUS have that allowed it to succeed and grow, when many open source project stagnate?

I think it's because of the architecture. Not just of the software (though that helps), but of the larger social group surrounding it. The following qualities are vital to getting community involvement in an Open Source project:

  1. Modularized code.
    Not only must the code be easy to understand, it must be easy to add new features. The pluggable module interface ensured that it was easy to add new modules. The benefit of the design was shown quickly, when many modules (LDAP, SQL, etc) were added quickly after the project started.
  2. Fast acceptance of patches.
    There's nothing worse than submitting a patch for a bug fix or feature enhancement to an open source project, and having it ignored. It's discouraging, and usually means that you'll move your efforts to something that's more productive. In the end, the project loses, because it loses features and bug fixes that everyone needs.
  3. Public mailing lists.
    Not only the “users” or “help” list has to be public, the developers list has to be public too. The developers have to be active on both lists, to help users, and to have public discussions about the design and direction of the project. A welcoming attitude to open discussion means that more people contribute, which means that the project gains the benefit of everyones expertise.
  4. Public CVS repository and bug site.
    Allowing people to submit bugs and view the source code ensures that they can find out if other people have run into the same issues they see, and what the solutions are. People are more likely to use a piece of software if they see that it is under active development. They can use an unstable version from CVS to get the feature they need, which means thay don't use another piece of software.
  5. Fast development.
    An incremental approach to development is better than the “big bang” approach. Don't underestimate the power of a series of small fixes. The small fixes means that the project almost always works, which means people use it and debug it. The small fixes also mean that new features are available quickly, which again means people use those features and debug them.

All of the items discussed above are important, but it's interesting what I left out: documentation. While documentation is useful, it doesn't help most developers, who are the ones driving bug fixes and new features. Documentation is useful to end users, of course, which is why I'm writing the book.

Finally, the items discussed above are all really variants of a common theme: Low barrier to entry. The easier it is to get work done, the more work people get done.

It's not rocket science, but it's amazing how many open source projects fail because the founders run the project with high barriers to entry.