How to track a projects extraneous quirks

Question

It's possible that the answer to this question may just be standard bug tracking software like jira or fogbugz, but I'm kind of hoping someone out there knows a better system for what I'm describing.

My most current project is requiring a lot of setup quirkiness to get into a position where I can actually start a coding section. For example:

• A series of convoluted internal company commands before I can insitgate an SSH.
• Making sure any third party classes that make external calls have internal company proxy options setup - while also making sure these setting wont be set up when installed on a production environment
• Making sure the proxy is set before trying to install pear packages.
• Other similar things, mostly involving internal IT security and getting it to work with modules and packages.

Individually none of these things is a huge deal, and I've written extensive notes to myself regarding exact commands and aditions I've made, but they're currently in a general text document and it's going to be hard to remember exactly where what I need is far down the line. We also have several new staff starting soon and I' rather give them an easier time of setting up their programming environments.

Like I said, they aren't 'programming quirks' exactly, but just the constant fiddling that comes about before programming starts in earnest. Any thoughts on the best way to documents these things for my own and future generations sanity?

Answer 1

We use a wiki to host instructions like this. Makes it easy to have everyone know a common place to access the information and keep it up to date if things change in the steps.

If there are parts that can be automated that is a good idea but we always create a page for the development environment setup if it requires non standard setup that someone will have to repeat.

Answer 2

Encapsulate each of these tasks into a script of some sort (bash, python, applescript, autohotkey, whatever is appropriate for the task).

Then create various meta-scripts to call them. E.g. "set_up_everything.bash".

In essence: Rather than spending time writing down everything you need to do, spend time writing a script/program that does everything you need to do.

If the scripts are written cleanly, they also become an ultimate form of documentation (just like any program).

Edit:

Rereading your question, this also strongly addresses your point about assisting new team members with getting up-to-speed: Have them run the scripts, and bam! And if the scripts don't work (due to differences in environment, etc.) they still provide a nice step-by-step of exactly the actions and commands that need to be made.