Improve documentation & explain what's actually going on

[hawkw]

Now that it seems like a lot more people are expressing interest in SOS, I need to remember to make the codebase more readable & understandable...