Contributing to the CS Documentation Project

The CS Documentation project is a resource that anyone can contribute to.

We do things a little different than would seem immediately obvious.

Historically, each document existed as a segment of HTML for each section. A server side script inserted the html verbatim into a template. This document described how to edit or create those types of pages.

We decided to move to mediawiki. It stayed on mediawiki for a year or so.

Now, the CS Documentation Project runs on a web app called smug, "better than a wiki, and smug about it."

The idea behind smug is to use the git content tracker to store content. You are free to store content in whatever format you deem necessary. Smug allows you to freely make edits, just like a wiki. The difference is that it doesn't open up these changes to the internet immediately-- that creates anarchy and a headache for admins. Wikis by nature are a prime target for spammers interested in raising the google rank for their web page.

If someone makes an anonymous edit, the difference is submitted as a patch. This is the same process that occurs when contributing to open source. The source is freely available, and anyone can edit it. If they see a mistake they are free to fix it, but a maintainer's eyes will meet the change before it actually gets committed.

Smug is powerful in its presentation layer. These documents appear to be flat html files when looking at their URLs. They are in fact ReStructuredText documents that are converted to html on the fly. Smug can convert these same documents to PDF on the fly. Flat files can be served as well.

In a nutshell, its a wiki with twice the power and capability, without the anarchy associated with it.