Useful Links

News!

Community Documentation Effort

As of May 2010, we have started a community documentation effort. This effort will increase the usability, content, and formatting of the current documentation. We will be using Restructured Text for the format. It is easy to create, easy to read, and can be converted to a number of other formats (HTML, PDF, etc.)

Please read the RST quick reference" guide for an introduction to the format. It is plain text, with minimal markup. An example of the new format is available on GitHub: load-balance.rst. The document looks much better than the old version.

How to Contribute

Github makes it easy to contribute. You will need an SSH key, and some familiarity with git. For those who don't use git, please just edit the documentation directly, and send the new version to the freeradius-users list.

  1. Set up an account on Github. The help page contains a lot of useful information. See the "Setup" link on the right side of the page for detailed instructions on using git, SSH, etc.
  2. Fork the freeradius-server repository. See also the FreeRADIUS-specific git instructions.
  3. Send an email to the freeradius-users list, saying which file you plan to edit. This step helps avoid multiple people working on the same file.
  4. Edit the files in the "doc" directory. Don't bother doing the usual configure / make / make install process. It isn't necessary.
  5. Push the changes back to github
  6. We will integrate the changes from your version into the "master" version
  7. Periodically pull everyone elses changes from "upstream"
  8. Enjoy better documentation!

Long-term Goals

The longer term goals of the project are to radically improve the existing documentation. That goal can be reached by following a few simple steps

  1. Convert the existing documentation to RST. Don't worry about content, cross-references, English grammer, or spelling mistakes. Just do a simple conversion for formatting.
  2. Re-organize the files to have consistent names. This step allows people to "guess" where the documentation is located, and to have their guesses be correct.
  3. Cross-reference all of the documentation. RST allows cross references, and we should use them! This step allows us to create an HTML version with all of the documentation linked together for ease of use.
  4. Audit the files for text that is out of date, or just wrong. Fix the text, and point to any new documentation.
  5. Write more documentation! Howtos, explanations, etc.!
  6. Adding documentation from the Wiki. It's probably best to have one "canonical" reference for all of the documentation. The current Wiki has had files added to it over time by many people. This means it's not as well organized as it could be.

The result should be a large set of clear, consistent, and high quality documentatation. Thanks to everyone for your efforts!