Regardless of the size of your project, software documentation is undeniably important. From the initial requirements and policies, to design overview and source-level implementation notes; writing any combination of the above will only help make your project better.
Unfortunately though, many programmers will repeat ill-thought out mantras such as "no docs are better than out-dated docs." This is a terrible ideology to subscribe to- it's akin to saying historical archives aren't important as they don't always represent the absolute current state of accepted truths, which is non-sense. While documentation may become out of date quickly, it does not tend to become obsolete quickly. As archives in any other arena do, they often give you enough insight and perspective into the decisions made which can help substantially in understanding the current state.
Luckily however, I don't think I've met someone who truly believes in this. Most programmers read documentation on a daily basis and love talking about how their own software works with coworkers, having no fear of poisoning the minds of their coworkers with soon-to-be-outdated information. I think the problem is often that they aren't willing to invest an effort into learning a documentation process that they may perceive to be inefficient, convoluted or that involves too much overhead, which is very understandable.
Maintaining a pragmatic workflow and at the same time writing documentation is hard, but there are many options based on the size or focus of your project that I'd like to discuss today, as well as suggesting a light-weight approach I use when all else fails.
After a recent late-night QuakeLive session, I was curious to know how exactly it worked. Having never written a browser plugin, there were a lot of questions running through my head. How much porting was actually done as far as the engine was concerned? Can we use new technology like WebGL? Did the networking layer have to change to deal with browser restrictions?
With a free upcoming weekend, I set out to answer these questions by getting the excellent ioquake3 project up and running in the browser and document my process along the way.
A "journalistic-motorcycle-stunting-gypsy" would probably best describe my role in the summer of 2011. My personal project fueled by pure passion had led me to travel a criss-crossed path from ocean to ocean across America for the majority of 2010 and finally over the Atlantic to experience the European version for 2011.
This passion of course is motorcycle stunt riding.
It had captured my Type A, but paradoxically still shy and reserved teenage imagination in high school and ravaged my life like the bubonic plague from that point on. At 15 I started practicing the evolving urban sport and carried it with me to Los Angeles for my first job in video games. Seven years later in New York City I was still stunting and finally my hobby peaked with the decision I should take a sabbatical from my professional career to dedicate my time and skills to help it grow into its fledging maturity.
My girlfriend (also a stunt rider) and I decided to start a news website and provide regular and reliable news, event coverage and how-to information on this underground, entirely DIY sport. Our goal was to help grow the sport and allow anyone with the interest the opportunity to take part. The sport attracted social deviants, like most alternative hobbies and the sense of family and sweet taste of real accomplishment made men out of boys and confident, contributing humans out of rebellious, misunderstood characters.
StuntBums.com was born and we hit the road in 2010 to learn everything about the scene in America. With a whirlwind of success we saw our project taking off and decided we wanted to expand the project to Europe for 2011. After a lengthy and stressful visa application process, we touched down in France mid-February and by May we were ready to spend the summer on the road with a van, a caravan and two motorcycles in tow.
For more information on StuntBums, we wrote a three part series about its history over the past two years starting here.
Lately I've spent my free time working on a generic, distributed build project along the lines of Electric Cloud or Incredibuild. One of the main components of this system involves not only executing processes remotely, but to synchronize the input and output files for each operation between the systems.
Along the road to coming up with a robust, battle-ready solution I tried many things. Finding the right balance of security, practicallity and ease of setup was a trying process (yes, I'm looking at you OpenLDAP).
In the end, most of my attempts fell into one these two categories:
- Sandbox the remote process's i/o, sending over any input files before execution and sending back any new files upon completion.
- Tunnel all file i/o between machines through some clever mechanism so that the remote machine is working directly in the requesting machine's file system.
