A Basic Document Storage Structure

A simple folder structure for storing project documents and support files

Last time I proposed this directory structure I was tortured, put onto a rocket and launched into the Sun (I survived, a little crispy, but alive).

Why is the folder structure I use so radical? Probably because it looks too simplistic to work. But I assure you, I have been using this structure for years now with great success (even on large projects).

Now, without further ado, here is the folder structure:



Hard to believe, but that’s all that’s really needed. The simplicity is driven by two factors; one, you can’t find anything anyway when you use a convoluted/deep directory structure, and secondly, its habits which make this approach work.

I can see some of you gesturing to the head-torturer, indicating your desire to use the iron maiden, but bare with me whilst I explain.

One question which may come to mind is do you name the top level folder after the client or do you name it after the project? The temptation, and I have seen this done, is to create a structure like this: Client Name->Project Name. For example; you would have the folder Acme, and under that you would have Blue Widgets and Hyper Widgets (nb. these would be two different projects belonging to the client called Acme).



A consistent hierarchical structure like this makes sense doesn’t it? Well, it does if you want to place the information you constantly need to access an extra click away. So which is it? Most of the time I use the client’s name. The reality is most clients will only have one project done with you, perhaps with maintenance being carried out on it in future. Flat structure is what it’s all about.

(Archive) - I have a ‘never delete’ policy. To a certain extent, it’s more about me not wanting to waste time trying to figure out if something should or should not be deleted. Back in 1993 when I had a 106 megabyte hard drive, storage capacity was an issue, it isn’t any more. The (Archive) folder is the key to making the folder structure work. Old versions of documents and support files get dumped here, this prevents the Documents and Media Dev folders from getting cluttered. As a general rule; if in doubt, back it up.

Documents - funnily enough, this is where your Word documents go. You put any kind of support documentation in here, be it PDFs, an Excel spreadsheet, or a Visio wireframe. I generally set the folder to show the most recently modified files first. You tend to work with the most recently created files the majority of the time. It’s important to move super-seeded documents into the (Archive) directory, otherwise the Documents folder can become unwieldy, especially on big projects.

Media Dev - this contains any imagery or multimedia content related to the project (e.g. logos, Photoshop files, Flash animations, videos, etc).

“Yeah, but the project has millions of documents” I hear you say. True, it does happen. But that’s what F3/Search was designed for. You are going to need to find older documents by keyword anyway. Plus there’s nothing wrong with having sub-folders if you really feel the need (e.g. Acme\Documents\User Manual).



At the end of the day, its pretty easy to decide which folder things go into, your files are either going to be a document of some sort, or a image/video. A quick note on file naming. Your company probably already has a system of some form, the only thing which I have to offer is recommending that you append a revision number on the end of documents. For example, spec_acme_rev_02.doc as opposed to just plain old spec_acme.doc. You may already have the revision number contained inside the document, but a person would have to open up the file in order to see it.

Hiring Programming Staff (Part 1)

Hiring great programmers for your development team (part 1)

Note: this article is split into two parts because of its length. The two segments are related, but each can be taken as a stand-alone article. Part 1 deals with phone interviews, part 2 focuses on written programmer tests.

The Phone Interview

Few would argue against the notion that the people on a project are the single biggest factor affecting its success. You could have an effective software development methodology in place, but inexperienced or unsuitable coders could destine a project to failure.

The task of finding a good programmer to join your team can be quite difficult and time consuming. I have to admit, I’ve done it the hard way in the past. A few years ago my boss and I spent an entire week trawling through résumés and interviewing people. We received around 240 applications and ended up interviewing 18 people. Needless to say, we got nothing done that week as far as our regular work went. This experience lead me to believe that there had to be a better way of finding top-notch programmers.

A starting point would be to post your job ad on a popular recruitment website (e.g. SEEK, or whichever online service has the biggest market share in your region). The structure and content of your job ad is ultimately up to you, but beginning with a short paragraph describing your company culture is a good idea. A common feature of job adverts for programmers is two separate bullet point lists; one for ‘must have skills’ and another for ‘highly regarded’ skills. You may also want to ask people to fill-out a skills matrix when they apply, this does two things: firstly, it weeds out ‘job spammers’ (i.e. people that just blindly apply to everything), and secondly, it provides a normalised method for comparing people instead of just relying on information which may or may not be contained in their resume.

After a few days, résumés should start arriving. Generally what I do is open up a résumé, press Ctrl-F and perform a keyword search for the most important requirement for the role. For example, if I wanted a .NET programmer, I would look for the keyword ‘.NET’ in a person’s résumé, if that particular word didn’t appear anywhere in the résumé, next (i.e. the candidate lacks the most basic of requirements).

There is an optional step you can do before contacting an applicant, and that is to ask them to complete an online test. In this situation, you would first review someone’s résumé to ensure they have the minimum skills for the position, then email them a URL to your online test. Based on the results of their test, you would decide whether its worth investing further time for a phone interview.



An online test does however require commitment of time to mark answers, but it will ensure that only the most technically competent people are progressing further. And yes, I am aware that a person can ‘cheat’ on online tests. For instance, they could have a friend sitting beside them helping them out, or they could be Googling the answers. But personally, that’s what I call ‘being resourceful’, besides, they will still have to survive a written test when they eventually come in for a face-to-face interview.

If you find a résumé that seems to be a match for the position you are trying to fill, then its time to consider a phone interview. This is where many people go wrong, they organise a face-to-face interview straight away. I believe this is totally unnecessary, you only need to meet perhaps 3-5 people from the total pool of applicants.

Now onto the phone interview. I work from a predefined script, a document about 2-3 pages long with questions relevant to the position. The first set of questions are what I call the ‘deal breaker questions’. If any of these fail, then you wrap up the interview and move on. The very first question always concerns communication. If you can’t understand what the person is saying over the phone, there’s really nothing you can do for them (you would terminate the interview).

The remaining questions would either relate specifically to the technology you are using within your organisation (e.g. “how would you rate your C# skills?”) or would be made up of very common interview type questions (e.g. “give an example of when you had to work under pressure”). To keep things simple, you generally rate a candidate’s answer as either ‘Bad’, ‘Fair’ or ‘Good’. As to how you asses an answer, that’s fairly subjective. However, each question can have a different weighting on its score. The reason for this is because a good answer to the question “what would you do if a project was running behind schedule?” is far more significant then a good answer to the question “why did you leave your last job?”. Conversely, if a candidate answered the question “how would you handle a difficult client?” in a negative manner, that may result in an actual deduction of points.



After concluding the phone interview, there is a Post Interview Analysis where you score the candidate on factors such as what their attitude and demeanour were like. These characteristics may be relevant if you are intending for the programmer to interact directly with clients. Finally, you tally the candidates score - the highest scoring people are the ones you want to interview face-to-face.

Where do recruitment or employment agencies fit into the picture? They are fine for the preliminary process (i.e. résumé review and talking to a candidate on the phone). They can be very effective in helping to short-list quality candidates. Do they need to be meeting and interviewing a candidate in person? I don’t believe so, it’s unnecessary and adds to the expense of the whole process.



A topic worth mentioning is the choice between hiring someone with a few years of industry experience vs. a recent uni graduate. There are pros and cons to both options, but it generally comes down to two things; personal taste, and how much money is available for the new staff member’s salary. Unfortunately, in-depth discussion of this topic is beyond the scope of this article, but I will say my own personal preference is to hire new graduates because they cost less and often have excellent production potential when given clear instructions.

Reviewed by Petras Surna

Sign-off Agreements

Getting closure on a project by using a sign-off document

A Sign-off Agreement is simply a document both client and technology supplier sign at the end of a project. In essence, it signifies that a client is happy with the work they have paid for.

You could say the Sign-off Agreement officially marks the end-point of a project, generally trailing behind UAT (also called System Acceptance). Could you close a project without a Sign-off Agreement? Of course, you may be thinking this process is overly bureaucratic, and that may be true for certain situations.

So, what's the point of the Sign-off Agreement? One reason behind it is to give everyone involved in the project a sense of closure. I would say this idea of closure is a good thing, for one it gives the development team a feeling of achievement. Another important aspect is it sets up a boundary relating to version control (i.e. version 1 is done). The concept of versions for web software is somewhat meaningless because of the ease with which updates can be delivered. However artificial, versions can be good for creating dividing lines between a delivered software package, and its next batch of features.

Probably the best answer on whether you should use a Sign-off Agreement on your project is 'maybe'. It comes down to a few key factors; the type of project you have, the kind of client you are working with, and the situation. For instance, if you are dealing with a government body then a certain degree of governance and process is to be expected. As often as possible, do try and use a Sign-off Agreement, but if you are in a situation where you need to concentrate more pressing tasks, then this process is a good candidate for culling.

An important aspect of the Sign-off Agreement is to make a statement about your Software Warranty. This is where you say how long you will be fixing bugs for free, and also what your definition of a bug is. Another way to think of this is as a rudimentary service level agreement (but without any commitments on turn-around time). Failing to discuss the idea of Software Warranty with your client leaves things open to interpretation and can setup the wrong expectations (e.g. a client may just assume you will be fixing bugs forever). How many months should you offer a warranty for? I don't know, that is really up to you. I have seen 3 months, 6 months, but I also know someone who basically fixes bugs for free no matter how long ago the software was delivered.



I like to keep the Sign-off Agreement to one page since I believe people have better things to do with their time then read long documents. I start with my Document Purpose section so someone picking up the sheet of paper can understand what it is about within a few seconds. The format of Sign-off Agreement I use is not designed to be water-tight from a legal perspective, that is not its purpose.

Towards the start of the document, I have a block called Agreement Parties, this just makes it clear who the client is and who the technology supplier is. The statement about the Software Warranty follows soon after.

The bulk of the document is the Terms section. The main point here is to say that your company has fulfilled all its contractual obligations and that the client is happy with what you have produced for them.

Something you may wish to discuss in the document is a maintenance rate for feature additions post-launch (also putting a time limitation on this quoted rate). I will probably be moving away from this style of agreement in favour of more flexible system involving Maintenance Blocks, but this is a discussion for future, after I have had a chance to road test the concept.



The last part of the document is an area for one of your company representatives to sign and date, and an area for the client to do the same (it is called a sign-off agreement after all).

A good tip for using a Sign-off Agreement is to give your client plenty of notice before presenting them with the document. It looks kind of legal, so it may make a client feel as though they are being backed into a corner and are about to relinquish control over their project. It’s important to explain what it is early on, for instance, just before or after UAT.

Reviewed by Patras Surna. Rev. 02.

User Acceptance Testing

A formal process for demonstrating project completeness

Ever had a project where you thought you were done, but the client had other ideas? The project schedule may say all tasks are done, the QA tester may have successfully run through the System Test Plan, and the programmers may have cleared all known bugs. So why wont the client settle their account and let you get on with your next project? Easy, they don't know the project's finished, and why should they unless you can demonstrate without a doubt that you have delivered on everything you promised.

This is where User Acceptance Testing, or UAT comes to the rescue (also known as System Acceptance). It's not quite the finale of a project, but its getting close. You could say the Sign-off Agreement or Project Post-mortem is the real project end point. In essence, System Acceptance helps give closure to a project, without it, you may have a tough time convincing a client to sign the Sign-off Agreement (where the client formally indicates they are happy with the work you have done).

The actual structure of the document I use for System Acceptance is quite simple, filling it in is the tricky part.



The idea behind the System Acceptance process is to first make a list of every screen contained in the system, then you arrange a time to go sit with the client and systematically go through all the screens with them. For each screen, you ask the client two questions; 1) does the page appear error free?, and 2) does it perform all functions according to the spec? If the screen passes these criteria, its initialled by both you and the client. If you're thinking "oh god, doesn't that get really tedious after about twenty screens?", you are absolutely right. But as painful as it is, it will produce the desired effect; a tangible sense of closure within the client's mind. I recommend you forewarn the client of the less joyful aspects of the process, explaining that there will likely be multiple sessions lasting a few hours each, and that the process may seem inane at times, but you ask that they bare with you.

Now for some inconvenient truths. Will you complete the acceptance process in the first session you book with your client? probably not. As a rough guide, allow ten minutes per screen, a twenty page web application could take over three and a half hours. However, what tends to happen is the client really starts thinking about their software once they realize its almost over, its their last chance to make changes before they become indisputable feature additions. The result is that you may get side-tracked. The other issue is that a UAT session isn't meant to be a critique of interface cosmetics or functionality, but it can easily turn into such a discussion.



If the time consuming and tedious nature of UAT weren't daunting enough, there is another looming danger; bugs. Chances are good the client will discover bugs during the acceptance session. If you've been wondering what the 'Comments/Notes' column was for, now you know; to write down bug details. What will probably happen is a good portion of the screens will pass, and some wont. You will have to make arrangements for another session with the client after you've had time to get the bugs fixed. Eventually you'll have all screens signed off, then you are ready to present the client with the Sign-off Agreement.