Developing Your Team Standards

One of the most common chores in any development team is establishing an agreed set of standards for use within the wider development group.  Typically, the team lead is responsible for either contributing directly to – if not solely responsible for – the authoring of a standards document that defines how your deliverables are shaped.

The most common scenarios I’ve seen are when a new Technical Team Lead has been appointed to the role (or been press-ganged into it) and a hospital pass is handed to that lucky candidate to own the task of getting the standards up to date, implementing them, or in more extreme cases, writing them from scratch.

I’ve found myself in this situation on more than one occasion and it is a completely overwhelming prospect when there is little or nothing to start from.  In this post, I will give a quick run-down of the key things you should include in your standards documentation and provide you with a working sample that you can adapt and improve as needed.

Starting From Scratch

Starting from scratch is probably the most intimidating position to be in.  You will often be lumped with this problem if the team is new, or if you are new to the team and no one has bothered to get around to it yet.

If you need to build out your standards from the very beginning, here are a few questions and considerations you need to address:

• Architecture: Classic or SOA? What layers should you generally have (e.g. presentation, data access, business logic, security, etc.)?  What clients does your business usually target (e.g. thin, fat, mobile)?  What integration concerns do you need to standardise?
• Technologies: What code is accepted / disapproved? What data storage and retrieval technologies should you use?  What scripting frameworks?  What languages?
• Tools: What testing frameworks should you adopt?  What about mocking? What version control systems and policies do you have in place? Continuous Integration?
• Documentation & Support: What are your minimum documentation expectations? How should your code be commented / documented?  Do you use documentation generators (e.g. Sandcastle, Live Documenter)?  What are your peer review expectations?  Who needs to be considered at handover when coding is complete and ready for delivery?

Updating Existing Standards

Being tasked with updating your company’s existing standards is a much more problematic situation.  The existing standards may either have evolved or stagnated over time and may not, in their entirety at least, reflect the true nature of your current development landscape.

Standards Review Process

The trouble is in the sorting of which content should remain, which should be modified and which should be removed altogether.  Start by identifying those standards that are completely obsolete or irrelevant to your current work; unsupported frameworks and languages, obsolete tools or unneeded documentation requirements.  Once this housekeeping task is taken care of, you can start on the more challenging part of adding new content in.  Pick your top problem area and define a workable approach to eliminate or minimise the impacts from that area.  After a couple of iterations, review how that standard is working and refine it.

When you feel that your team is operating well on this functional area, pick your next performance issue and repeat the process.

Documentation Isn’t Standards

It is quite common, especially in larger organisations, to have explicit provisions for various documents included as part of the team’s development standards.  Different people have different views on this topic, but my personal view is that documentation does not constitute a development standard; it is part of your process.

There are no doubt times when you need to supply a solution architecture document, design document or some other written artefact, but this is most often an internal requirement and does not affect how the actual product is designed and coded.  As mentioned before, unless it adds direct customer value, it isn’t really needed.

Your team may have some procedural requirement that outlines all the written material that is expected for a given deliverable, but this is effectively meta-content that only supplements the product – it doesn’t underpin it.

Don’t standardise your documentation deliverables unless (and even here I’m not that convinced of the need) there is a direct customer benefit and the standard can be scaled to both small and large solutions.

10 Commandments

As a pretty good rule of thumb, your full standards document will probably grow and evolve to become something of a behemoth.  You can expect your new developers to read this a total of once while they are still

1. Full of enthusiasm about starting with a fresh new company and are eager to impress
2. Bored out of their brain while they ramp up their understanding of how your team works

After this, you can expect your full standards document to be referred to in about one in every 100 cases.  This is normal (unless you run a code dictatorship, in which case you have bigger problems than whether your compliance rates are 100%).  It is because of this that you should have a standards 10 commandments list – preferably in soft copy (e.g. on your team’s SharePoint site or similar) that is easily found.  These ten commandments should summarise – in bullet form – as briefly as possible what your top ten minimum expectations are.

An example might be:

1. Code must be checked in to version control at the end of each week at a minimum and must not break the build.
2. Unit tests must accompany all complex code and should ideally drive the design of the behaviours they test.
3. JQuery is to be used as the accepted JavaScript framework in all web applications.
4. Code should have full XML comments such that they are sufficiently descriptive when documentation is generated from it.
5. Hungarian notation will summon the four horsemen of the apocalypse and should therefore be avoided at every cost.
6. Never write from scratch in JavaScript that which can be found in a stable, supported jQuery plugin.
7. Include only those features that have been explicitly asked for by the customer.
8. Major features cannot be released without first passing a peer review.
9. Business values and variables should never be hard-coded under any circumstances.  Offenders will be exiled to supporting IE6 for the rest of eternity.
10. HTML should never be rendered explicitly through code.

A list of key concerns such as this doesn’t undermine your larger standards document; nor does it replace it.  It is a quick reference so that developers can get an immediate grasp of your expectations around delivery.  If further information is needed, the standards document is where this should be found.

Baseline Standards Document

Having outlined all the considerations for writing a good standards document, it seems almost unfair to then expect you, dear reader, to then go off and write the whole thing from scratch.

Start by having a look at this development standards baseline document and see whether it might serve as a good starting point for your own internal documentation.  This document is written with Microsoft .Net shops in mind – particularly web application producers.  However, it should be easily adaptable for any development situation.

Much of the content is taken from the Microsoft Coding Guidelines site, with business-specific content prepended.

Hope this helps.  Enjoy.

Opening New Doors

At the end of this month I’ll be leaving my current job to start at a new company in a new town.  I’ll be taking up a position of Technical Lead for a finance company in Dunedin, New Zealand and will also be tasked with providing strategic technical input to the company’s service offerings.

This is the first time I’ve actually had the word “Lead” written into the role, which to many people might be quite alarming.  Why hasn’t this job function been formally recognised before?  The answer is that in all my previous roles, I have built a new team from scratch as a senior developer and the job description has never really adapted to reflect the broadened job functions.  This time I’m going into an established team and therefore a pre-defined recognised position.

Given that my job function will now require me to actively manage my team of developers (as opposed to the implicit “develop first, workload management second” expectation of my previous role), I feel I have finally reached a point where I need to place considerably more focus on my management skills.  This will be a challenge because, like many technical team leaders, I’ve had very limited chances to observe really good management in action.  Much of my line manager’s day-to-day activity has happened “behind closed doors”; precluding me from learning the tasks and challenges I need to understand.  To quote Esther Derby and Johanna Rothman, “poor managers create the illusion of productivity through busyness”.  Fairly or unfairly, my line managers’ productivity has often seemed illusory because it was actively hidden through unshared calendars, high levels of unavailability through absence and a lack of communication.  I should point out here that I am not suggesting my managers have always been unproductive.  Merely that I have not been given an opportunity to understand how they structure their workload to create an effective management style.

So I have elected to seek out an alternative source of management training in an excellent book called “Behind Closed Doors” by Esther Derby and Johanna Rothman.  As I progress through my new role, I will be writing here about my experiences in learning about the people and the work, building the team and its capabilities and identifying areas where my team can add real value to the business overall.  I’ll look at how the development team’s commitments and capacity are placed and how I can strengthen the team’s processes and throughput.

My next post (due at the end of June) will look at my first week on the job and the challenges I face in learning a new company’s products and services, my team’s role in facilitating those and how I ease myself and my team through the processes of Forming, Storming, Norming and Performing.

My hope is that these regular posts provide some valuable insight for others in similar situations.  I would be very surprised if I was the only one who found himself faced with these new challenges and hopefully I can pass on some experience and useful ideas to you along the way.

Managing Your Software Mortgage

Technical Debt

Every developer has at one time or another faced the situation where the client asks for a “minor change” to the stated requirements.  Often this might be wording, layout or styling.  Other times it could be a functional change that appears to be a minor tweak but has far-reaching impacts that cause your household appliances to eat your pets.

The difficulty (at least for me) arises when the client says something like

It’s just a small change, isn’t it?  It should only take you an hour at most

This always makes me uncomfortable because I want to do what the client’s asking (I like to please people) and from their point of view, they’re quite right that the change they’re asking for appears to be a very simple one.  However, I also know from experience that since they’re asking for this change during our release phase (i.e. we’ve done testing, UAT and pre-production) and it Just Can’t Wait it’s extremely risky and means that the testing I’ve done will effectively be rendered invalid and my version control will no longer reflect what’s being released into production.

So what are some good counter-arguments to clients who simply have to get that one last JavaScript animation on that text block?

Your Software Mortgage

Your Software Mortgage is the technical debt you incur whenever you have to “just get it done” at the expense of code quality or attention to process.  This might mean you don’t comment anything and just throw it together quick and dirty in time to meet your deadline or you don’t document this part for your handover & support notes.  The upshot is of course that you’ll have to go back and do it right at some point.  The cost of having to do this instead of concentrating on your next iteration is your technical debt.

It’s not a 1:1 relationship either.  To get your code back to an acceptable standard (“paying your mortgage off”), you have to forego spending time on your next set of deliverables.  This means that not only is the client paying for deliverables that can’t be started yet, they’re also paying again for work that has already been delivered.  In order to make your debt repayments, you either need to deliver the next set of requirements early (ideally without incurring more debt) or negotiate a reduction in scope for the next release.

In order to evaluate the cost of technical debt against cost of lost business opportunities, the client usually benefits from seeing the impacts in dollar terms.  This is would be easy if it was actual money being discussed, but technical debt is a more abstract concept and therefore difficult to quantify.

Quantifying Your Liquidity

Liquidity determines your ability to pay your bills

Being able to put an actual figure on your liquidity gives you more leverage to negotiate paying off your existing debt or avoid taking on new debt.

If your liquidity ratio is high (i.e. you have a high capacity to take on new debt), borrowing against your software quality will likely be less of a risk and you may feel more comfortable taking a quick and dirty approach in order to meet a deadline.  However if you have low liquidity (i.e. you’ve already taken on a lot of debt) there is considerably more risk in falling further behind on your mortgage payments.  As already mentioned, your code base must be maintained to keep a minimum standard of quality and supportability or you risk Software Decay:

[Software Decay is] …code decayed to the point in which fixing anything in a hazardous proposition – every fix is likely to break something else.

So how do you calculate your liquidity?  Accounting has a number of different approaches, but most are more complex than the abstract idea of software management allows.  However, the current ratio, which is the simplest measure and is calculated by dividing the total current assets by the total current liabilities can be loosely applied to code.

Depending on how granular you wanted to get with your reporting, you could either measure Lines of Code (LoC) or discrete functional blocks for a broader view.  Let’s assume you have exactly 100 separate methods that made up your application.  If your latest release required that 10 of these methods were rushed through and needed work, your current ratio would be 100 ÷ 10 which (obviously) equals 10; or – to put it another way – a ratio of 9:1 (i.e. for every code block needing refactored, you have 9 others that are considered optimal).

Deciding what constitutes an acceptable ratio depends a lot on your application’s complexity and size, but a general guide might be that a ratio of 3:1 (i.e. 25% of your code needs refactored) should be considered to be the maximum sustainable leverage your code base can afford and anything over 2:1 should be setting off alarm bells.

In short, keeping your unintended debt down gives you more room to intentionally take on debt when it’s useful to do so.

Risk Ratio

The later through the development / deployment process a change is submitted, the greater the risk associated with it becomes and the higher the cost to fix the consequences of that risk is.  If the client is asking for a change to be made after all testing phases are complete and the release is being deployed, it stands to reason that there is a much higher risk of introducing new problems than if the change had been done in the design phase.  This Risk Ratio is the proportional increase in the amount of work required to fix something relative to when it goes wrong.

The Risk Ratio is an extremely valuable bargaining chip that quantifies the potential cost to the client of their requested change.  It forces them to consider the financial impacts of the change from a cost/benefit perspective.  An example Risk Matrix that has risk weightings from a scale of 1 – 10 looks like this:

	Requirements Analysis	Requirements Review	Design	Build	Functional Testing	User Acceptance Testing	Deployment Testing	Release
Typographic (spelling / punctuation)	1	1	2	2	3	4	5	6
Copy (text / wording)	1	2	2	3	4	5	6	7
Cosmetic (styles / layout)	2	2	3	4	5	6	7	8
Functional (client-side)	2	3	4	5	6	7	8	9
Functional (server-side)	3	4	5	6	7	8	9	10

This matrix provides a quantifiable measure of how serious a change is based on the iteration’s progress.  You could use this as the basis of a calculation to determine the potential cost in dollar terms for any adverse impacts resulting from an unplanned change.  For example, if the client requested an existing style to be changed on your web application during your UAT phase and that style affected the layout for three pages, then you are tell the client that based on experience, there is a 60% chance that introducing a change at this point will cause a problem further down the line.  Given those odds of just under 1 in 3, there’s an extremely good chance that one of the three pages affected will suffer.

Alternatively, you can use this matrix to argue that any change being made at this point will require 6 times more effort to fix than if it had been raised during the outset of the project.  This is not an outrageous claim when you consider that the requirement might need to be formally documented, approved, developed, unit tested and acceptance tested again.

Technical Inflation

Technical Inflation could be viewed as the ground lost when the current level of technology surpasses that of the foundation of your product to the extent that it begins losing compatibility with the industry. Examples of this would be falling behind in versions of a language to the point where your code is no longer compatible with main stream compilers.

Managing your technical debt and inflation requires you to have a very clear understanding of how your debt is distributed.  Documenting candidates for refactoring is the best way to get a clear idea of the scope of work required to keep your application well-maintained.  This might be done using a source control system such as Microsoft TFS, where tasks, bugs and other work items can be recorded against a particular change or section of code; or using third-party tools such as AgileZen.  Think of this as your Application Balance Sheet where your assets and liabilities can be easily reported on.

Technical Inflation is a direct product of sustained low liquidity and software decay.  The longer you leave something before fixing it, the more expensive it becomes to fix.

Ensure you have a clear idea of how much debt your application currently has so that you can make informed and reasoned arguments against adding any more work to an otherwise hard-to-see pile.  If you need to push back on a client’s demands so that you can ensure the sustainability of the client’s application, you will need evidence of why.  Having your books in order is a critical piece.

Further Reading

Don’t Enron Your Software Project

Monetizing the Technical Debt

Technical Team Lead Charter

Documentation - The TTL's best friend

If you were tasked with writing a document that described exactly what it was that your function entailed, what would it look like? Would you write a Job Description; starting with Senior Developer as the basis and edited to include the additional responsibilities and roles you performed? Would its tone be descriptive or prescriptive? What would the HR department’s view of it be? Would they formally recognise it as an actual JD? Would they be a bit upset that you were stepping on their territory?

What about writing a longer essay that described your job function in greater detail? Would it become a description of an ideological role that you couldn’t really achieve in practice?

I was recently required to write just such a document: a Technical Team Lead “Charter” that described what my job function was, what the measurable goals of that function were and (as I found out later) something that would then be used as the basis of performance measures in the upcoming year.

My first attempt can be viewed here. Comments and feedback most welcome as usual.
Technical Team Leadership (PDF)
Technical Team Leadership (DOCX)

On becoming a Team Lead

Team leadership

I’m a bit stuck.  After having held the position of Technical Team Lead in my last three jobs, I’ve lately come to a point where I’ve started to do some reflection on my qualifications and experience and question what exactly it is that the role of Team Lead means.

The thing is I’ve only been in this development game for about six years. I finished college in 2002 where I’d majored in programming (VB6 was standard at the time) and project management and took up a job in the capital as a security administrator for just under a year before landing a job in a software shop as a helpdesk operator. 18 months after bagging and tagging calls, I finally managed to negotiate (or at times, even force) my way into a role supporting the company’s smaller ASP applications.

Not having ever worked on websites before, this was a considerable amount of learning for me. I then moved on to ASP.Net and started teaching myself C#. Over the following two or three years I built up a team of (typically) graduate developers to help me as the workload grew. Being the incumbent, I was informally given the title of Team Lead.

Now having moved on to a new job at a financial institution, I find myself again with this informal title of Technical Team Lead. I believe that – again – it’s not because I’m the most proficient, knowledgeable or even necessarily competent person on the team; simply that I’m the guy who said “yes” when the manager asked if I’d like to head up its formation.

So here I am after two years in the role and finding that in reality, I’m not actually that well-versed in the basics. I’m having to remind myself what the point of interfaces are and how abstract classes work at a fairly rudimentary level. I don’t really know how to apply design patterns to my code or even what many design patterns are, for that matter. I blurted out to one of my team that I didn’t know what Domain-Driven Design was today. I now feel I must learn and understand it.

The problem – for lack of a better term – is that I’ve risen to the position of Team Lead quite quickly. I haven’t built up my core knowledge and experience as thoroughly as my peers because I’ve often been concentrating on a broader range of responsibilities. In my roles I’ve been responsible for reporting, invoicing, timesheet approval, documentation, design, architecture, customer meetings, requirements gathering… all manner of things that aren’t related at all to actually writing code.

So does this mean I am right to be concerned about my qualifications to lead a team? Well, yes and no.

The first point to note is that, at least in my experience, the role of Team Lead is one in name only and is rarely recognised formally by the organisation. All the company wants is a senior developer (typically with 5 or more years experience) who is prepared to sacrifice some of his involvement in the core development process for the administrative and project coordination tasks that are effectively outside a “regular” manager’s field of expertise. The Team Lead will be able to see the tradeoffs between the various technical aspects of a project while being able to clearly communicate relevant information to the business or client in non-geekspeak. In other words, leading a team is not entirely about having the highest level of technical skill out of all the other members; it requires equal measures of people, communication, writing, and time management skills as part of the day-to-day routine.

The second point is that I’ve risen from a support desk analyst to senior developer in a fairly short space of time – about 6½ years – which (I like to think) is some reflection on my abilities. However I do recognise that this has come at the cost of not having obtained some of the core experience that might otherwise be expected of someone at this level. Still – a key part of solving a problem is recognising that the problem exists in the first place and being willing to act on it. That is where I find myself today: identifying gaps in my knowledge and creating a set of personal plans and goals to correct those gaps.

So over the course of this blog, I am going to chart my thoughts, challenges and personal lessons in my capacity of Technical Team Lead / Self-Doubting Developer. I’ll look at how I started in the team lead capacity by growing my own job function, growing a team around me and what sorts of events and capacities I’ve worked through since.