How to track a projects extraneous quirks

Question

Hello, 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

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.

Answer 2

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 3

Plan A: Eliminate the dependence on external systems by setting up a proper test environment that you can control. This may involve setting up dummy databases, mock SOAP servers (SoapUI Mockservices), etc. You should try to get to a point where you can treat all of the externals as black boxes, which you can control with these mock/dummy/stub services, with minimal re-configuration (like swapping .ini files, for example).
Ideally, it would be a drop-in environment "appliance", such as a directory zip file containing whatever databases, executables, etc., are needed. Perhaps on a flash drive.

No, I do not live and work in such a utopian environment either! But this is, as I envision it, how it should be done.

Plan B: Assuming that you can't do the above, you're stuck with testing against externals such as "live" networks and servers. i.e. your database query runs against somebody else's test database server, and you hope it's got the same data in it that it did the last time you tested. So you need to have a minimum set of tests that can be run to ensure that the external envionment is the same as it was last time. Could be yesterday, last month, last year. Suppose you need to retrieve employee records from the HR test database. Ok, so have a test app that ensures that it can connect, login, query the records, and compare the result set against the "last known good" result set. Now you're good to go. If you don't get that far, work through it (fix your login, endpoints, hostnames, proxy, set up an account, upgrade drivers, etc..) BEFORE you worry about coding/testing/demo'ing the rest of the system. This will save lots of time, and should prvent attrition of new devs that give up and quit after 3 days because nothign works.

Update: And whatever you do, check it into version control so you can go back, compare, etc..

Answer 4

Write scripts to automate this. Time spent doing this will pay for itself over and over-- you'll save time day-to-day and save time bringing new developers into the fold.

You may need a separate "bin" project separate from the codebase for these tools. Start out with the easier tasks, and progress to fill in all pieces. SSH can be scripted securely with the right token pairs. Tools like capistrano or chef are quite popular. The approach is to one small piece at a time, and the goal-- perhaps you won't attain it-- is full automation.

A couple years back this would have sounded like crazy talk. But these days every one of our projects can be checked out and run with no twiddling. (A side effect is the continuous integration is trivial to set up.) It's even possible to have single button that provisions a server from AWS, installs and OS, all needed tools, checks out our app from github and deploys it. Just did it the other day! Have faith!