Dream big in 2011

23 December 2010

The EndGame Moleskine

Nothing shows potential like a blank piece of paper.

It can hold words, thoughts, sketches, eureka moments, hard won conclusions.  Given the right treatment it can even fly across the room.

So … what could happen if you filled the blank pages in this journal with your words, thoughts and sketches?  If you dreamed for a bit, then picked up a pencil, what could you design?  What is waiting to be built?  What investment could lead to something great?

Dream big in 2011, then design well, build well, invest well.

Happy Christmas and God bless.

Andrew, Jamie and Simon.

www.end-game.com


SCM with Accurev

3 November 2010

Starting a new software project (or company!) gives you the opportunity to have a clean slate with the tools and processes you’ll use. Starting EndGame – I figured that to be genuinly agile, we needed to have agile tools, not just agile ideals. I adpoted the YAGNI policy when it came to tools and our development environment and only introduced a tool when we absolutely needed it. It took us 5 months before we needed an issue tracker – until then, google docs did the trick.

One thing we did implement on day 1 was AccuRev, and its changed the way we build and deploy software. AccuRev is a software configuration management” system that allows an agile approach to development and lies at the heart of our entire development process. I’m going to describe how we’ve deployed AccuRev across the 10 or so projects we’ve worked on this year, but first – a few definitions for the pre-AccuRev readers:

Depot: a depot is like a repository and we have one per product/client. A depot represents a walled development environment – allowing product and client work to be kept separate from other depots.

Stream: Accurev has streams instead of branches. Streams represent your work environment, with stage downstream from production and development downstream from stage. To push a change package to stage, you drag it from the development stream to the stage stream, and like-wise to push it live.  All changes flow automatically downstream, so its like an automated merge between branches everytime you promote.

Promote: like doing a check-in, promoting pushes your source code upstream. In the first instance, you promote to the development stream you’re working in, and from there we promote to a staging stream, then to production.

Change package: a set of source code files that have been changed due to a work issue.

Here’s how we’ve got it working for us:

1. The roadmap
Everything starts on a whiteboard or with user feedback and makes its way into a backlog. From there, we plan out our time across various projects and clients using Hive – the project scheduling tool we’ve been developing this year. Hive allows us to plan out milestones and high level goals and make sure we’re not over-resourcing.

Using the Hive API, we then pull out the milestones to provide a high level roadmap on our project dashboard.

2. Work and Issues
Once we’ve decided on high level goals of the next cycle(s), we convert it to work/enhancement/defect issues using AccuRev’s built in issue tracker – AccuWork. We looked at whether to use a third party issue tracker and integrate it, but Accuwork is quite a powerful system and is fully integrated with AccuRev. To provide an integrated project dashboard, we built a UI over Accuwork so that work issues can be linked to hive milestones and hooked into project documentation. It also allows our project dashboard to track progress in a cycle of work done vs budget.

3. Documentation
We’re pretty light on documentation – most revolves around a whiteboard and visual designs, however there’s always need for some level of written requirements and specifications. Within our project dashboard, each work issue can be linked to a page in our Wiki, so the spec is only one click away. The flip side is that when viewing a page in the wiki – all related issues can be listed. Once in the wiki, each page is has a variety of related pages, so its easy to jump between related specs. Our wiki uses Zoho docs and spreadsheet editors inline to provide an OK rich editor.

4. Accurev streams
Streams are where Accurev really stands out. For each product, we setup a new depot and create streams for production, stage and dev. Because we’re a small team we usually only need one dev stream, but Accurev supports multiple downstream and parallel streams. Development happens in personal workspaces and work is promoted against an issue number in to the dev stream. From there, we can promote issues to stage and from stage to live. By promoting an issue, it pulls all source changes with it. This allows us shift a change package associated with a single issue from stream to stream just with a simple drag and drop. We may have 10 change packages on stage and pull just 5 to our release candidate site. After another check of the RC, those five issues can be drag-and-dropped to the production site to deploy them.

5. Promote triggers
When we promote to dev, stage, or live – an Accurev trigger fires automatically and updates the status of all issues that have been promoted. When promoting to stage or live, release notes are created with a list of issues and promote comments (and posted automatically to our Yammer feed and project dashboard). This keeps the issues up to date and also provides a record of what we’re working on – again, giving customers more visibility of progress on their project.

6. Automated build and deployment
Automating builds and deployments changes the way you work. We use CruiseControl.NET to deploy to our stage and live sites and it works beautifully with AccuRev. Because of AccuRev’s streams, CC.NET is only deploying the change packages in a stream. So, where you typically might have an integration branch that you’re developing into, rolling to stage and eventually rolling to live – in AccuRev you’d have three streams instead. The live site is built and deployed against the live stream, so will only include change packages that have been promoted to live. Same for stage. So, building and deploying a site is now independent of what developers are checking in – its all about what is being promoted upstream (and sometimes demoted again!). For a small dev team, we’d never go to the effort of separating all these steps into separate branches, so AccuRev gives us a process that is incredibly robust without massive overheads.

7. The project dashboard
I’ve mentioned a few times about the project dashboard. This is a web app that we’ve built that pulls everything together and gives visibility to the team and the customer. It includes:

- Trackers of cost vs budget, pulled live from our time tracker (Freckle)
- Trackers of work completed, pulled live from AccuWork
- Trackers of google analytics, twitter, sales metrics and usage metrics for each app
- Summary of the roadmap, pulled live from Hive
- Work issues, pulled live from Accuwork
- Wiki
- Status updates

Providing some confidence around price and a roadmap can be hard with an agile process. At the beginning of a project, or a cycle, the client usually wants a price and we plan it to the best of our foresight. The question then becomes whether this is a fixed price or an estimate of time & materials. We work with a mixture of both – typically a fixed price for a small project that is a single dev cycle or a license and estimates for the larger projects. This raises the issue of how does the customer have some confidence that they’re going to get what they are paying for. An approach of “we’ll work down the prioritised list until we run out of budget” is fairly risky and relies on trust. This is where our project dashboard comes in as an attempt to give the client full visibility of what’s happening in the project – in realtime.

 

That’s a snapshot of how we do SCM as of 3 November 2010.  I’m sure it will be improved by the beginning of 2011, if not by next week.  If you haven’t used a system like Accurev before, I can recommend joining one of their webinars and seeing just how important it is to have agile tools as well as agile intentions.  www.accurev.com.


What we’ve been up to this year

14 October 2010

I haven’t talked much about the projects we’ve had and have on the go this year – but I intend to!

In the meantime, we’ve finally got ourselves a simple website (minty!) that highlights a few of the projects we’ve done this year. If you’re interested, have a look here: http://www.end-game.com.


Managing Javascript & CSS source files

3 September 2010
Early on in the development of Hive, we realised we needed a better way to manage javascript and CSS. As the javascript files got bigger we started having source code merges (shudder) and we occasionally would ship a version with debug code still in it.

There are some really good systems out there for optimising javascript & CSS, but we thought we’d start simple and see how it went. We’ve now rolled this system out over four applications and its working great.

To avoid source code merges, small and frequent check-ins are good, so using a source control system like Accurev where each developer has their own workspace is perfect. Its also easier to maintain code and avoid merges if you can have one javascript class per file – but you end up with lots more files, which can make loading a page slower.

To solve this, we create as many javascript and CSS files as we need, then merge them on the fly. This allows a single url /scripts?version=x to download all required scripts and an XML file manages which scripts will be merged and returned. We also threw the Yahoo YUI library in there to minimize the javascript and CSS and reduce the overall size.

The other issue we were having was with debug code, swapping between debug and production libraries and remembering to remove console.log commands. To solve this our XML file specifies a target, so the web.config can control which javascript files will get included. We also use some REs to strip out debug commands on the fly.

Overall, a dead simple solution to solve 5 problems:

1. More files means easier to maintain and fewer source control merges
2. On-the-fly merging means only one javascript & one CSS per page, resulting in faster page loads
3. Minifying the code means smaller javascript and CSS
4. Stripping out console.log and other debug code means we can leave it in and not worry about it in production
5. Swapping between debug and production versions of libraries is automatic

We can highly recommend the YUI compressor for .NET – which we use in this code snippit:

public string GetJavascript()
{
    try
    {
        // Get the files from the XML index
        List<string> scriptFiles = GetJavascriptFiles();

        // Load the contents and put into a string
        var javascript = MergeFiles(scriptFiles);

        // Optimise
        if (_Target.ToLower() == "live")
        {
            // Strip out console.log, etc
            javascript = RemoveDebugCode(javascript);

            // Minimise using Yahoo YUI
            javascript = JavaScriptCompressor.Compress(javascript);
        }

        // return the result
        return javascript;
    }
    catch (Exception e)
    {
        return e.Message;
    }
}

Business Cards!

1 September 2010

We’ve been in business for 7 months so its about time we got some business cards printed, especially since we’ve finally settled on a logo!

The company is called EndGame, so for a bit of fun we thought we’d put a maze on the back of the card.  The point of a maze is to get to the end, ie that’s your EndGame.  Beautiful.  The logo is sort of half isometric, so we figured the maze needed to be isometric so that it could join up with the logo as the finish point.

Anyway, one thing led to another and soon I’m playing with a depth-first algorithm to create the maze, a winding number algorithm to keep the maze inside the right space and drawing lines at 30 degrees in SVG.

But that wasn’t enough, if we can draw one maze, then why not draw 1,000 mazes, so every card can have a unique solvable maze.  Everyone’s EndGame in life is different, so this seemed like a good idea.  To quote our printer, “that is out there and very different haha “awesome” and no -one has ever done this in my 20 + years of printing so your a first … ”.

That’s it.  If we’re the first, then there’s no going back.


Hive in BETA

26 August 2010

Its a relief to see Hive finally out there in BETA and to see the feedback starting to flow in.  Hive is a project we’ve been working on this year and has been a lot of fun.

Hive is a SaaS app for scheduling projects and people.  Its perfect for people with a team and a bunch of projects to manage.  Its based on the premise that most people hate project management and hate project management tools even more.  Hive lets you do in a visual, fun and collaborative way what people revert to spreadsheets for – to get visibility of what projects are on the go, who is working on them and to make sure you’re not over (or under!) capacity.

Hive is built as a one page web app and its always fun to run it in full screen mode and have people not believe its a web application.  We’ve had a lot of fun working with Darryl Gray who designed this stunning application.  Its been nice to have a project where we can make use of  the shiniest new CSS and javascript techniques with lots of drag-drop and animations, integrating SVG and wiring it all up to give a seamless user experience.  Seamless except for the bugs of course – but that’s what a BETA version is for!

As far as features go – the best of Hive is still to come.  Under the hood we’ve implemented live collaboration and its quite fun watching another user’s changes animate on your screen (this isn’t available in the current version).  We toyed with allowing viewstate changes to be sync’ed across users too – which is fun, but I’m not sure if its that useful.  Because Hive is based on an event model, we’ll be adding undo and redo support soon, but I’ll have to save details of that for another blog post.

We’ve also got some great reports, sharing, publishing and integrations planned, but the most important features to add going forward will be the ones asked for by users, so make sure you sign up at www.tryhive.com, have a play and send us your feedback.

p.s. The screenshot above features a slightly older version of the UI.  The latest version is even nicer.


Finishing – part 2

11 August 2010

“The end of a thing is better than its beginning, and patience is better than pride.”

Put another way, finishing is better than starting.

So true and yet so hard.


Charts: buy, build or borrow?

6 August 2010

Its the same old question everytime you need some software. Do I buy it, build it myself, or find someone who’s already got it and convince them to share it?

Like any software developer, my first instinct is to build it – but then the business side of my brain kicks in and I start thinking about stuff like opportunity cost and cost/benefit.

We had this choice to make recently with charts and the answer was obviously to use one of the many great solutions out there. But, in the end it didn’t stack up and I was surprised that the right choice was just to build our own.

We were looking for something that …

- Could render to HTML, PDF, iPhone, iPad (rules out the great looking flash and javascript options)
- Could get 20 charts in a PDF with high enough resolution to show each chart full screen and without blowing out the size of the PDF (rules out using images)
- Would give us complete control over styling including being able to change style mid-series (rules out half the options)
- Is configurable via an XML template (rules out the other half of the options)

Actually, configuring any chart from XML is pretty standard when it comes to presentation, but not when it comes to the data. Charting solutions are generally not aware of the context of the report – they are only aware of the data values being plotted. We wanted a solution that could be aware of the full report, so that we could quickly change the data being charted. Like in Excel – when you have the data in one sheet and you can pivot/sum/group/etc and chart whatever you like.

So, our solution was to build a .NET SVG charting library that is report aware. SVG gives us full control over the style of each chart, series and data point.  Instead of just outputting SVG, every aspect of the chart can be styled using SVG.  It also allows us to render numerous scaleable charts to HTML and PDF without blowing out the file size.  Most importantly though, the charts are aware of the report context – so a chart no longer plots points – it plots a formula over the data. For example, to show a conversion rate, the formula “SALES / VISITS” could be used in the chart (where sales and visits are two predefined metrics). This gives us a few advantages:

1. The chart can be customised via XML or a UI to show any visualisation of the available data. A quick update and we’re now showing SALES and VISITS as separate series and comparing them to last year, or filtering by region.

2. Charts can be synchronised across a report, ensuring a consistent use of colour and allowing some smarts for visualising the data best.

3. Charts can be interactive on the web. A user can drill into the conversion rate to see how it was calculated, or highlight an area of interest, or filter the report by a particular region, or pivot the chart. We borrowed the dimension/metric/date model from Google Analytics to give data as many dimensions and metrics as we needed and introduced a hierarchal subject, allowing data to be easily rolled up and summerised.

It turns out that drawing the charts is the easy bit and managing the styles and data behind the charts is the high value bit that is sorely lacking. The false ecomony in our case would have been to buy the bit that draws the charts and then to have our options severly limited for managing the styles and data.

We’ve already deployed these charts over three projects with more to come, so the investment is paying back fast too.


Finishing

28 July 2010

We’re in the middle of the “finishing” phase of three v1 projects right now, and since my software lifecycle on this blog is sorely missing any comment on finishing, I thought I should share a few thoughts.

Firstly, what is finishing? Its what used to be called QA or testing, where the developers hand over to the test team and then retrospectively update the specification to match what’s been built.

I’m not that fond of the QA at the end of a project approach. If you look at risk based testing, then you identify risks up front and work throughout all stages of the project to mitigate the risks. When you get to the end of the project, there shouldn’t be that much QA left to do – just finishing. We all know that the last 5% of a project takes far longer than 5% of the time and this is a really important time where hundreds of small decisions are made.

The other thing I’m not fond of is this tension between QA being at the end of the cycle so there’s always time pressure, but also the idea that developers should hand over completed bug-free code. I tried that once and all it meant was that I had to go through the entire QA process myself (which I’m really bad at) – just to hand it over to be QA’ed again.

Finishing is about shipping working software. Its when the feature development is complete (or when you hit the 80/90% mark in your cycle or budget) and when developers, testers, BAs and everyone else involved start to focus on shipping instead of building. There will be bugs to fix, there will be missing functionality to build, there will be enhancements, there will be style changes, there will be a lot going on and its not all QA. The goal is to turn a feature-complete project into a quality shippable project and it doesn’t rest on the shoulders of the test team while the developers move onto the next project.

So, finishing is actually quite fun, I just wish we stopped setting up our projects to converge like this!


Search

22 July 2010

We needed a site search in a website we built recently, so we tried out Google Site Search and its great.  Using the $US100 per year plan, we’re able to have a fully integrated search with about 24 hour turnaround on indexing.

Google site search looks at the XML sitemap (http://www.tribedesign.co.nz/sitemap) to get a list of pages to index and the priority of each page.

One of the main pages on the site is the portfolio, which is a dynamic page using ajax to load products.  To make each product searchable we created a unique url for each product that includes the product details in the html then listed these with higher priority in the sitemap.  We also took the FAQs and ‘Making it easy’ pages, which are full of rich text and split them into one page per FAQ/section to make the search results even more relevant.

It works very nicely with the search results embedded in the site and you wouldn’t even know it was powered by google, except by noticing the quality of the search results.

About TRIBE Design

Great things formed in metal begin with great design.  And, making the best of design means being a trusted expert of the craft.  Tribe is a design-led maker of metal products that touch an amazingly diverse range of people and purposes.  From military metalwear to motoring memorabilia, fashion accessories to film props, competition medals to corporate gifts, it all starts and finishes in one place, right here in New Zealand.

http://www.tribedesign.co.nz


Invest well

1 July 2010

One of the things I love doing is investing into business and software – but equally as much into my kids and people around me. EndGame refers to starting with the end in mind so that we can invest well.

Earlier this year I came across KidsCan (www.kidscan.org.nz), a charity in New Zealand that provides some basics to NZ kids in need. This struck me as a great opportunity to invest well. A pair of shoes, a raincoat and breakfast is a small investment into a child that will flow through into their whole life –  learning well, playing well, feeling well, holding their head high.

Have a look at www.kidscan.org.nz. $30 buys a raincoat or a pair of shoes and socks. $120 provides a child with breakfast for a year. That’s a good investment.


Hope Room

29 June 2010

We’re stoked with the new furniture in our Hope Room.

Why a hope room? Its a constant reminder that every meeting should start with a positive outlook, anything is possible. We’re here to be creative, to dream big. The Hope Room is a place to know your end game, and then figure out the next steps for getting there. Its also a term used by our friend, Bob Hartley.


Brand

27 June 2010

Five months into the new business, it really is time to do some branding (or at least get a business card printed), so last week we sat a few designers down in a room and told them to go for it. Of course, brand is a whole lot more than a logo, font and some colour. Its a promise, a story and all that. Well, it took us three months just to come up with a name, thinking of all that brand stuff without sounding cheesy is hard.

Anyway, here are some ideas – feel free to comment and cast your vote for or against cheesy-ness.

EndGame

- Well planned, well designed, well built, well invested
- We know our end game – and what steps to take next
- We know what we’re good at – and what to say no to
- We like to win – but we enjoy the road there more
- We love quality – and we love it more when you can’t see it
- We do things well – and we will always do better next time

And here’s the EndGame arrow, which is in the process of being tidied up, fattened, coloured, drop-shadowed, 3D’ed, un-3D’ed – but hopefully very soon will be featured on a business card and which points up because that’s where we get our inspiration from.


BusinessSavvySoftware.com

22 June 2010

Is it just me, or are people generally getting tired of “experts” who’ve done it once, then become full time coach?

I am, which is why I switched off google reader at the start of the year and stopped blogging.

I really admire people who’ve succeeded, then back themselves to do it again instead of just advising others how to do it.  That’s how Xero started and there’s so much more to learn by watching people do it than talk about it.

This year, I started EndGame – a software house that is full of purpose and I love it.  Its much more fun to do the stuff than to read about it or just talk about it.

There is some stuff that I’m itching to share along the journey, so I’m reviving this blog under its proper URL BusinessSavvySoftware.com and maybe, one day, I’ll even get it designed since RSS readers are so last year.


Who to employ first?

22 February 2010

For a startup business, its one of the biggest questions, risks and costs – who do I employ?

In any small business everyone wears a few hats, so it would be great to find someone who can do a variety of things.  But does that mean they are going to be expensive?

The good old rich vs king argument says you should employ senior people if you want to be rich (but lose control because you don’t hire someone with experience and ignore them) and you employ less senior people if you want to be king.  I’d rather just have someone with a hunger to learn, a can-do attitude and a good fit for the culture I’m trying to build.

So, here’s the first three people I want to work with:

#1 has got to complement my skills and since we’re building web applications – that means I need interaction design, graphical design and a CSS/JQuery guru.  That might sound like three people – but like I said, you’ve got to wear a few hats so lucky I know just the person and between us we can cover the entire process end-to-end and build some stunning software.

#2 there are a lot of possibilities here, but the best is someone to focus on my weakness(es) – which is the operations side of things allowing me to focus on development and running the business.  I’ll never forget one of my best customers saying to me, “I love your product, but the only time you ever talk to me is to chase money – so I’m going to switch to this other product”.  Without good operations, its so easy for things to spin out of control – so having someone to take care of this side of things will be massive.

#3 is to replace me.  I want to run the business, so I need to replace myself as a developer.  I also want to have time to learn about the parts of business that I don’t have so much experience in, so I figure I’ve got to make myself redundant as a developer.  Not that with 2 developers I’ll exactly be redundant – but at least we can deliver software without me getting in the way.

I’m really pleased to have found great people for the first two roles – people who share my values and excitement for what lies ahead.  #3 will have to wait a little longer, but if its you then I’d love to hear from you.


Tweet4YourTee4Fun

16 February 2010

Tweet4YourTeeOur first micro-site is up and of all things – it sells tee-shirts!

Check it out: http://www.tweet4yourtee.com

Over a Roti Chenai a couple of months back, we were talking about having a play with the Twitter API and how we could have some fun.  The idea hatched that it would be cool to have a tee-shirt with our Twitter name on it – so Tom and Warren went to work designing a site, designing some tees and organising the production and distribution side of things and last week we built the site.

The site still needs a bit (well – a lot) of tweaking, but we’ve managed to make use of the Twitter API in a couple of ways.  The homepage shows the twitter name of the last person to mention @tweet4yourtee, the On Twitter page shows the most recent conversations with @tweet4yourtee and the order page will automatically apply a discount to your order if you’ve mentioned @tweet4yourtee in a tweet.

Thanks to the reach of Twitter, the first sale happened within an hour of the site going live and while I wouldn’t say its spreading virally, its fun seeing hundreds of people hit the site after seeing it tweeted.  The tee-shirts are quite nice too – I’m wearing mine now and there will be a few on display at WebStock this week.


The first 10 things

27 January 2010

Today is the first day of starting a new company (the name of which is yet to be decided) and this is by no means a top 10 things you should do when starting a company, but here are the first 10 things I’ve done – in no particular order.

1. Seed capital
First things first, cash is king so got to sort out some cash to get things going.

2. Xero
I’ve spent the last three years building the best accounting system ever, so I’m really looking forward to finally getting to use it for real!
http://www.xero.com

3. Life chair
After sitting in one of these for the last three years, I just had to get one.
http://www.formway.co.nz/Products/Life.html.

4. Server
I thought long and hard about what to do for a development server and in the end was really impressed with Erin from Unleash who offered me a perfect ex-lease server with very reasonable hosting.
http://www.unleash.co.nz

5. Accurev
I met these guys in Boston 18 months ago and was well impressed with their SCM system.  They are the smartest agile guys I’ve met and I’m really looking forward to using their system.
http://www.accurev.com

6. Employee
Its great finding someone who’s skills complement your own and it means that the projects are pushing forward even when I’m out schmoozing over coffee.

7. LiquidPlanner
Like it or not, my company will be doing timesheets.  Partly because we’ll be doing some chargeable work, but mainly because I want to know what I’m investing into every product & idea.  LiquidPlanner has very nice project planning and prioritisation and employees get a nice to-do list which they can estimate against and track their time and progress.
http://www.liquidplanner.com

8. Pray
Yep -  church doesn’t have a monopoly on God so I want to know how God & business mix and I want to experience stuff like this: “But the people who know their God shall be strong, and carry out great exploits”

9. Intranet
Managing and sharing information is key, so getting an intranet in place is a top priority.  In this case, I’ve started building my own … who knows – maybe one day I’ll productise it.

10. Office
Sitting in the sun in the garden at home, drinking Tuatara Pilsner is nice, but I’ve got to be in the CBD – so the great guys at Mindscape have agreed to let me crash on their couch (so to speak) for a while.  Thanks!  http://www.mindscape.co.nz

Now for the work to begin, I’ll share a bit about my first few projects soon(ish).


My ceiling is your floor

31 October 2009

My third son was a week ago, Benjamin Micah Butel.  Benjamin means ‘son of my right hand’ – and I have no idea what the person who made that up was thinking, but I know what it means to me.  It means my ceiling is your floor.  I don’t want my boys to repeat my footsteps, but to take what I’m capable of and go far beyond.  Its like a relay race where I pass the baton on (with my right hand) and they run the next leg.

As leaders, we establish innovative and creative ways of doing things, then formalise it so we can train other people to do them.  So often, this becomes a constraint when it should just be the starting point.  My ceiling is your floor.  We should be empowering people to start with what we’ve learned and go further than us with their own creative ideas.  Instead of expecting them to run the same race as you (ie do it this way because that worked really well 5 years ago), instead pass the baton so they can run the next leg of the race starting with your best and then creating their own.


Words are cheap

16 October 2009

0909nnn1-300x176

We all know that a picture speaks 1,000 words, but even more important than pictures are actions.  Actions speak louder than pictures and words.

You could write and talk all day about doing something, but its worth nothing until you do it.

That’s one of the reasons why I like the Agile Manifesto:

  • Individuals and interactions over processes and tools
  • Working software over comprehensive documentation
  • Customer collaboration over contract negotiation
  • Responding to change over following a plan

peoplematter432-copy1-300x182


Documentation is expensive, but its necessary

12 October 2009

We need documentation to help us achieve optimal communications and control; however we also understand that documentation can be an overhead that doesn’t add value to our customers.

There are two types of documentation and you should always be aware of why you are writing documentation and for whom.

Project documentation is for communication
Project documents are used for communication within a project and are not maintained once the project is completed. These documents are necessary to:

  • Sell the concept
  • Remove ambiguity
  • Facilitate a multi-location team
  • Manage the details

Product documentation is for management and control
Product documents are used for managing and controlling the product and will be maintained until the product or feature is retired. These documents are necessary to:

  • Manage priorities and scheduling
  • Maintain quality standards
  • Maintain correctness
  • Educate people

When you’re using documentation to communicate, then you’re capturing the state of the requirements etc at a given point in time. If the requirements change, then you don’t update your original communication, you make a new documentation to communicate the changes clearly.

Communication isn’t a living document.

However, when you document for education, then it is a living document. If the requirements or scope changes, then anyone reading your old document for education purposes will be misled, therefore in order for your document to meet its purpose, it has to be maintained. This means every time you write a document for education purposes, you’ve just added an overhead to your project – a document that has to be updated as the project changes. If you are not going to maintain the document – then you aren’t writing it for educational purposes. To make the maintenance cheaper, the document can contain less detail and more principals that are less likely to change.


Follow

Get every new post delivered to your Inbox.