I suspect that one of the reasons for a lack of contributions to the body of knowledge is people feel rather vulnerable offering opinions in writing on a public forum. Committing your untested view to writing can be a daunting prospect, especially when you lack confidence in your ability to clearly express yourself in writing and your audience is well informed and apparently well established on the forum/site. I know I’d benefit greatly from such a forum, even though I contribute to blogs and forum debates now.

While it is satisfying to exchange ideas in forums or through blogs, it is not quite the same as a more real-time interactive session. There is simply no substitute for sitting down in a relaxed informal environment and talking over a subject that interests you. Things like the ALM Expo help but I think they are still too formal and often little more than a series of marketing pitches by vendors, which is not what I’m looking for. I want a sort of ‘watercooler’ or ‘drinks in the bar’ exchange of ideas.

I want to move away from a stultifying formal environment, where we feel our every word is being judged and consequently we feel the need to be ‘professional’ at all times, into a more relaxed environment where we can have a proper conversation.

To this end I have looked at a number of possible mechanisms for sharing and interacting in real-time.

One obvious method is the webinar. Most webinars I have seen get the format horribly wrong (or rather, they corrupt the format into something so far removed from a webinar that it’s unrecognisable). A webinar should be like a face-to-face seminar (a host makes a short presentation on the topic at hand to stimulate participation, followed by an extended period of dialogue between participants). Most ‘webinars’ that I have attended are little more than a marketing pitch in which the host presents their product (sometimes thinly veiled behind some more general question) followed by one or two selected questions. This format is more like a lecture but would be more accurately described as ‘ad-inars’. Completely useless for what I want, which is a dialogue, an exchange of ideas—in other words, what I would expect from a seminar/webinar.

Then there are broadcast forums such as BlogTV. Again, while this is primarily a broadcast medium, the interactive chat available to all viewers does provide the audience with a means to direct the ‘show’ by asking questions and challenging the presenter. So, perhaps a little more of the dialogue I am looking for; a chance for people to ask questions and challenge the host’s views. BlogTV also has the opportunity to co-host, allowing for the interesting possibility of debates, interviews and the like. BlogTV’s non-commercial nature also, in my opinion, makes it more relaxed and less formal than some other formats.

Another interesting possibility is the chat room style interaction offered by services like Stickam or YouCams. These allow several people to interact via audio/video links while others contribute in chat format. People can “step up to the mic” when a slot is released, making for a fairly dynamic interaction.

These five modes (blogs, forums, webinars, broadcast, and video chat-room) each has merits and shortcomings. I already participate in most of these formats but only the first two in a professional capacity. I find myself dissatisfied with the interactions provided by the forum and blog formats (it’s like having a conversation in slow motion and it takes too long to write the post and then spend time clarifying and resolving misunderstandings that could be cleared up in seconds face to face). So, what about the other formats?

Well, the most obvious problem with each of the other three is precisely their real-time nature. At what time should I offer to take part in them? I have good conversations with people in India, Europe, and the US and these cover a wide range of time zones. To cover all of them would require several sessions. Then there is the matter of when people can take part. Some of you can access audio or video at work, others cannot. Some are willing to take part in these sorts of conversations in your spare time, others are not. To reach as wide an audience as possible, to discuss the topic with as many people as possible and benefit from different viewpoints means running multiple sessions but obviously I want to make each session as relevant and accessible as I can.

How many people want to spend their spare time talking about their profession? When I first thought about this my reaction was ‘not many’, but then I thought, ‘but you want to, there must be others like you’. But maybe I’m just strange? We shall see.

All of this musing lead me to the conclusion that the only way to proceed was to ‘give it a go’. So, over the coming months I will be setting up some open webinars, doing some BlogTV, and coordinating some video chat-room sessions. Some will start with a specific topic, others will be more open-ended. I will try to run sessions at different times in the hope you can join in at least one of them.

If you are interesting in making your own presentation at a webinar (I want people willing to present a 10-15 minute introduction, a well framed question would make a good introduction, to stimulate dialog—no vendor style ‘ad-inars’), or you want to co-host a blogTV session, then contact me and we’ll sort something out. If you want to participate but cannot find a suitably timed session then contact me and let me know your time zone and when would be a better time for you (no promises, I do have to work and sleep too ).

Oh, and if you have any suggestions for topics for these sessions, let me know and I’ll see what I can do.

I will blog, tweet, post to the CM Forum, and announce on the ITSLM Body of Knowledge web site all of the sessions.

Whether I continue with these will depend upon whether people are interested in participating (there’s no point in them if people don’t take part).

I hope to speak with many of you in the near future.

Sometimes the questioner will provide some clues about their specific circumstances, but inevitably the answers will reiterate, “it depends”.

The correct approach to this problem is not to solicit ad hoc advice from internet fora, but to consider your own situation. The process is simple enough but requires that you put some thought and effort into finding the right tool. It boils down to the following steps.

1. Draw up a set of criteria to be met by the tools you intend to evaluate.
2. Draw up an evaluation matrix.
3. Create a shortlist of possible tools.
4. Evaluate the shortlisted tools against your criteria.
5. Get vendor demonstrations.
6. Get evaluation license installations.
7. Finally select, in as objective a manner as you can, the best solution for your predefined criteria.

An alternative strategy is to employ an expert in the ALM tools field, but they will follow this process anyway. Any other approach is utterly pointless. Let’s take a more detailed look at each step.

Generate a Requirements Document

You must have a list of requirements the tool is to satisfy (otherwise you would not know you wanted a tool). Formalise these requirements into a document. Be specific.

If the tool is to support version control then consider whether you need it to support branching, baselining, labelling, parallel development and so on. Do you need it to support locking to prevent more than one user changing a file revision at a time? If so, must this locking be provided at a revision, branch or file level?

Are there specific integrations you require? Must the tool integrate with developer IDEs? Do you have existing build systems that the system must integrate with, or do you perhaps need a system with an integrated build system? Do you have special tool integration requirements?

Does the tool need to track changes (workflow control of change requests)? Or perhaps you have an existing change request system that needs to work with the new tool?

Do you need to support specific platforms? It’s no use looking at tools that run on Windows platforms if your development uses Unix. Similarly you may (as is common nowadays) have many platforms to support. If so, make sure you specify those that must be supported (and perhaps some that would be ‘nice to have’ — there’s no use turning down a perfect fit for 99% of your environments just because one developer uses an odd platform).

Mario Moreira’s excellent  Software Configuration Management Implementation Roadmap (Amazon uk,us) is an excellent place to start in establishing your requirements.

Don’t forget the future! You may have a specific set of requirements now, but talk to your strategy team and find out whether they have plans to move to other platforms in the near to mid-term future. It may take many weeks to find and procure the tools, and once you have them integrated into your development process it can be tricky to change them, so make sure you are buying a tool set that will serve your needs for the next five years or more. (Sure, things may change in that time, but it’s stupid in the extreme to ignore what you know now. So plan ahead!)

The future is, they say, a foreign land and no amount of planning can anticipate every future requirement. Planning ahead is essential, but not guaranteed foolproof. Plan to transition to new tools in the future by including requirements for extracting data from the tool set you are investing in. This is a common mistake, tying yourself in to one system and finding it impractical to move to a new system later. Again, think ahead.

Formalise all your requirements into a document and review it with the stakeholders. Get sign-off from all stakeholders so that you know exactly what you need to find.

Draw up an evaluation matrix

Once you have the core requirements agreed on, draw up a simple evaluation matrix.

An evaluation matrix is a simple grid down one side of which are all your requirements. Next to each requirement put a weighting (a simple multiplier) indicating how important that feature is to your organisation. For example, you could use a scale of 1 through 5 (1 being optional and non-essential, and 5 being absolutely mandatory). Going across the top of the grid will be a series of columns where you specify the tools you intend to evaluate. This matrix can then be completed for each tool as you evaluate it when creating the shortlist (next step).

For each tool, you will enter a value indicating how satisfactorily it meets each requirement (0 for not at all, through to 5 for completely, for example). By multiplying the original factor with the satisfaction measure, you get a more-or-less objective value for how much each tool satisfies each requirement, and thus the degree to which each tool in its entirety meets the needs of your organisation or project. So, an optional requirement will always contribute less while a mandatory requirement will contribute more; and a tool that does not satisfy the criteria contributes nothing while a tool that satisfies the requirement completely contributes more.

There are many ways to adjust the way you calculate the value of each tool’s satisfaction of requirements (by adjusting the weighting factors or the way you calculate the final score), but whatever you decide to do, decide before you start evaluating tools and do not be tempted to fudge the results. We are aiming for as objective an assessment as we can get and it is tempting to see an appealing tool and try to adjust the weightings so that tool scores well. Doing this defeats the purpose of the evaluation; you may as well just ‘buy the pretty one’.

Draw up a shortlist

Okay, now you are ready to start researching tools. First, scan the internet for likely candidates. By all means visit forums and ask questions, but keep them both focussed and general. Ask people to suggest tools in general categories, for example: “I am looking for a change management tool to run on a Unix server that can be accessed from both Windows and Unix clients” or “I am looking for a version control tool that supports branching and merging and allows locking at the revision level”. Once you get these suggestions, go look at the vendor’s website and see how the tool matches your general requirements.

During this research phase you don’t need to be too specific, you’re just trying to get a shortlist of tools to add to your evaluation matrix and examine more closely.

Once you have your shortlist, you’re ready to do some more detailed assessments.

Evaluate shortlisted tools

A quick way to start your detailed evaluation is to send your requirements document (not the matrix, it won’t have any detailed description of your requirements) to the vendors of each tool. Make sure you contact the vendor and that you are dealing with a specific individual (you want to have someone accountable for making sure you get responses).

Only once you have responses should you move on to real evaluations. Oh, and any vendor that fails to respond should be dropped, after all if they can’t answer (or if they refuse to answer) questions then you have good reason to suspect their after-sales support may not be too hot either.

Okay, so you have your responses. Now add these to your evaluation matrix and add in your evaluations for how satisfactorily each tool meets your requirements. Contact the vendor (the person you dealt with when submitting your requirements) and get clarification as required.

Eliminate tools that score too badly from further investigation. (Of course, ‘too badly’ will depend on what you are looking for.)

The final part of your initial investigation is to check the vendor company. Are they well established? Financially stable? What do forums say about their support facilities? How often do they release updates? And, of course, how much will the product cost (based on list price at this point, your procurement department will deal with negotiating the final price of licenses)? Add these details to your evaluation matrix.

Now, and only now, should you approach vendors for demonstrations.

Get vendor demonstrators

Why leave it so late to see the tool in action? Two reasons; firstly, until you have requirements, and a statement from the vendor on how ther tool satisfies the requirements, you are not in a position to evaluate any demonstration. Secondly, it is very easy to be distracted by a generic shiny demonstration (I know only too well that generic vendor demonstrations have the ‘wow’ appeal, especially to non-technical managers, and it’s easy to be seduced). Generic pre-sales demonstrations are designed to look good. The vendor is showing off their tool. Of course it looks good. Of course it runs smoothly (although I’ve seen some howlers in my time). This is fine for showrooms, but terrible for purchasing decisions. Remember, we are looking for the right tool for your organisation, not the tool the vendor wants you to buy.

Once you have good evaluation criteria you can ask vendors to come and demonstrate how their product satisfies your requirements. Make sure you are clear when requesting the demonstration that you expect to see evidence of how their tool meets the requirements document that they have already seen and provided feedback upon. Do not accept a generic demonstration at this point. If they cannot, or are unwilling to, provide a suitable demonstration, strike them from the list — you’ve put in a lot of effort and are likely to be giving them a substantial amount of money in the near future, so they should be willing to show you what you want.

During the demonstration, make sure you see their tool perform to the requirements that they have claimed it fulfils. Get clarification on how marginally met requirements may be worked around (those that the vendor identified as only partially satisfied) and be sure that you see an unambiguous demonstration of all requirements that the vendor declared they satisfied completely.

During demonstrations, be fair. It is unreasonable to expect the vendor to show you everything you need. There will also be requirements that they state they only partially satisfy; give them a break and don’t harangue them for this. Accept the limitation. Discuss options. Make a note and move on.

Once all the vendors have demonstrated their products, re-evaluate them on your evaluation matrix. Add notes on where the demonstration failed to meet expectations, and where the demonstration exceeded expectations.

Eliminate any that fail to meet expectations satisfactorily.

Get evaluation license installations

You should now have a very short list of potential products (two or three if you are lucky). Obtain evaluation licenses for each product.

While no evaluation will be 100% true to life, this evaluation phase should be as realistic as possible.

In particular, make sure you can check out all the integrations you need and, if possible, make sure the product supports your real processes. Also, investigate how easy the system is to administer, backup and use. Run through common scenarios and make sure the tools perform to expectations. Use real projects, real code and real users for the final evaluation.

Finally, make a decision

Phew! It’s been a lot of work to get this far, but you should now have a pretty comprehensive idea of what the finally shortlisted tools are capable of.

Using all the information gathered so far you can make an excellent business case for the tools that best meet your needs. You can include details of the problems it will solve, the costs of the tools and their support, details about the vendors’ business, and the savings and contributions you anticipate the tool making.

How does one overcome analysis paralysis? One technique I have found useful is to simply do something. Often the process of starting down one of the available options is more revealing than continuing to analyse a situation in the abstract.

For example, suppose I have to select a new version control tool. I begin by clearly specifying my requirements for the tool. It is impossible to specify every requirement we have for tools like this, but a good start can be made in identifying the key features it must possess.

Having established the essential requirements for the tool I do a survey of the available tools and create a list of six tools. It is at this point I get analysis paralysis; there are six tools, each of them meet my basic requirements but each offers its own unique capabilities. Which should I choose? Should I look for more requirements to narrow the search? If so, where do I look for these new requirements? Which aspects of the tools are the most important to refine?

So, how do you break the analysis paralysis?

Get the tools installed on a test rig. Hook them into your normal development and test environments and try them. It really does not matter how quick and dirty these installations are at this point, you are interested only in doing something. As soon as you start this process you will begin to identify problems and benefits for each tool. You will begin to uncover subtle requirements that you missed in your main requirements gathering. And you will break the analysis paralysis cycle by doing.

Doesn’t this process waste a lot of time? Well, that depends how you look at it. When I have a clear view of what needs to be done then this process of do something is not necessary. I know precisely what to do, so randomly selecting one of a set of alternatives would be a waste of effort. If I am stuck in analysis paralysis then staring at the alternative, or wasting time digging into unknowns, really is a waste of time. Better surely to select one alternative and see where it leads, learning as I go what helps and what hinders my efforts.

This technique works whenever I get analysis paralysis. If I am writing, for example, I begin with a blank page and many ideas swirling around in my head. It can be difficult to start writing. The fear of wasting my time writing the wrong thing down used to cause me to write nothing at all. Then I realised that this was a stupid approach.

I find it is better to write something, anything, rather than to sit staring at a page trying to figure out what to write. Just dumping my thoughts onto the page helps me to recognise what is rubbish and what is useful. Yes, I spend time writing a lot that I eventually edit out of the final product (often I edit out more than half of what I write), but I still find this approach more productive than staring at a blank page for hours, then writing something that I still have to edit several times before I am content that it meets my requirements.

Don’t get me wrong. I am not encouraging rash action. Forethought and careful analysis is essential to being productive. I am simply offering a method I find useful to break out of the unproductive analysis paralysis loop.

When a product is demonstrated, online or directly, the presentation has, generally, been carefully worked out in advance to present to tool in the most favourable light possible. The tool will perform optimally and the use case will appear flawless. Sadly, real life is never an idealised case like this.

It is very easy to be beguiled by these idealised demonstrations, they look so smooth, so simple, and they seem to address some serious development issues. It is difficult to remain objective, especially when the tool seems to offer an easy solution.

Real life is not a demonstration though. It takes time to migrate to a new tool. Tools all have limitations, and you need to know what these are and how likely they are to cause you difficulties.

You need to know how difficult it will be to migrate your existing system over to the new system.  Many tools will demand that you work in a particular way in order to get the best from them, so remember to account for the cost of changing your process too. Are you going to need to sacrifice integration with other tools because the new tool does not integrate properly? Then there are training costs in order to get the whole project trained on the new tool.

Another irritant with many modern tools is the lack of a command line, or an impoverished command line that does not provide access to all of the tools functionality. The move to more and more GUI based interaction presents difficulties for real life scenarios where it is often necessary to integrate tools using scripts. Be careful of the lure of a powerful API. APIs are wonderful to have, but they are seldom as accessible as a command line interface, making quick integrations more difficult to implement.

Do not accept a demo as a reason to change tool. Demand that the tool vendor show your system using their tool. Demand that the vendor show how your system would migrate to their tool. Demand that they show the migration process, how the tool will integrate into your existing process or what you will need to change, evaluate the total cost of migrating to the tool, and so on. Any vendor that refuses, or cannot show the cost benefit of this migration should be dropped immediately from you evaluation. No matter how good the tool looks, no matter how well it performs with an idealised demonstration system, if it cannot perform for your system it is useless.

All of this may seem like I am arguing against looking at new tools, or that I have some downer on new tools in general. I do not. I love new toystools and I think tools should be constantly reviewed in order to make sure we have the best tool for the job. Just remember, the best tool for the job does not necessarily mean the newest tool and the newest tool may come at too high a cost in terms of impact on your environment and process.

We will look at every aspect of documentation, including each of the following.

• Audience — Who are you writing for? And, how to make sure your document appeals to them.
• Content — What are you writing about?
• Structure — Creating documents that make finding information easy.
• Presentation — Creating documents that are appealing.
• Delivery — The different methods of delivering information.

Many documents focus only on content, neglecting all other aspects. This is in part because many documents are written to the same formula by domain experts. They are not written to be read, they are written to comply with a requirement that they exist.

This series is not interested in producing documents for compliance, it is interested in producing documents that are useful and used.

Audience

When you write anything you must have an audience in mind. When writing this, for example, I have in mind people like myself; people called upon to write documents describing policies, plans, processes and procedures. In particular I imagine someone who has documented processes and procedures in the past but has been disappointed that their documents are not read or referred to by the people for whom they were written.

Why do people not read these documents?  To answer this question I would like to turn it around. Why do people read? What motivates people to read anything?

People read for two main reasons.

• Pleasure
• Acquisition of knowledge

It is unlikely that anyone will read process documentation for pleasure, but this does not mean process documents should be unpleasant to read. In later posts we will look at making documentation more appealing to read.

Most people will read process documentation for one of the following reasons.

• They must follow the process to achieve some goal.
• They need to be reminded of a process, required to achieve some goal.
• They need to verify that a process has been followed, in achieving some goal.

The common thread being ‘to achieve some goal’. The important take-away lesson for this section is that your audience is reading these documents in order to achieve some other goal. Technical documentation is not read for pleasure but for purpose. The reading of the document is a means to an end, not an end in itself.

The first step in writing effective documentation is knowing what your audience wants. What goals are they trying to achieve by reading your document? Answering this question will inform all other aspects of the writing process.

Knowing what question your document must answer for your audience is a big step toward writing a good document that will be read. Another important feature is knowing how your audience reads. By this I mean, knowing whether your audience is technical or not, do they understand a certain type of jargon? In short, you must know what sort of language to use in your document to make it as concise, intelligible and appealing to your target audience.

It is pointless writing a heavy technical document (that may be accurate and achieve the intended goal of you audience) when your audience has no technical inclination. They simply will not understand it, or at best they will have to work very hard to understand it – in which case they will not read it.

Identifying your audience

This is usually the easiest part of the writing process. Imagine who will use your document.

Most organisations have some form of review process. Unfortunately these reviews are too often performed by the wrong people and this leads to poor documents being produced. Too often documents are written for the reviewers and not for the users.

Suppose you are tasked with writing the build management process document for a large project. The review will include the project manager. You may end up writing a document for the project manager, but this is not the audience that will actually use the document. The only time that the project manager will ever see the document is in the review. The principal audience for the build management process document are the developers and build managers. You should be writing for this audience.

The project manager is important in approving the process, not in approving the document. This is a very important distinction. Once the process is agreed the project manager should only be involved in confirming that the document accurately records the process. They should have no other input into the document (unless they are also a developer, build manager, or other legitimate audience member).

Bottom line – write for the user, not the reviewers.

Next time I will look at selecting content.