Benjamin Read's code garden.

Project Documentation Templates

Published on

This article is about: engineering

Writing documentation for new team members - or just to provide a referenceable standard - is hard. I’ve provided these documents with the aim of helping this process.

I’ll be honest, I’m not naturally an organised person. But I think that gives me an advantage. It means I have to try harder to be organised. And because I hate the chaos that can result, I’m pretty determined to get things organised and keep them that way.

Consequences #

I suppose I don’t really have to revisit what happens when a project is disorganised, do I? We’ve all been there, and have perhaps been guilty of it ourselves at one time or another. But it has some pretty drastic effects:

  1. Loss of profit
  2. Developer disillusionment
  3. Project can fail to meet client expectations

All three of these can have a really bad effect on the atmosphere in any team or organisation.

Help is Available! #

I’ve just set up a repo of documents that I helped develop whilst I was at Blaze Communication. These practices allowed us to increase profitability, better meet client expectations, and they certainly helped developers feel more informed, empowered and invested in their projects.

Contractor Guidelines #

The Contractor Guidelines document sets out some principles for contractors. It was chiefly written for off-site developers. I have tried to avoid stipulating rules where possible but set down some best practices — “guidelines” that developers can hopefully use to work smarter instead of harder.

GitHub Link to Contractor Guidelines

Prelaunch Checklist #

It’s possibly the worst feeling in the world when a project has gone live and you realise you missed that key security feature, or forgot to activate this piece of functionality. It’s even worse to get a call from the client several weeks down the line asking for analytics data … then realising you forgot to add the code snippet.

This Prelaunch Checklist, from an original by friend and colleague Adam Maltpress can be used as a template for your projects.

GitHb Link to Prelaunch Checklist

Technical Manual #

When I was leaving Blaze I wanted to leave behind more knowledge to the replacement developer than I had the opportunity to say in a handover meeting. This “Technical Manual” sets out some broad strokes for a new developer, and can be used as a handbook for new developers to refer to.

GitHb Link to Technical Manual

Project Scope #

This is the most barebones of templates, and shouldn’t be too extensive. It should only outline some key deliverables, specifications and user stories that have been discussed and agreed by the client and the development team. As well as affording deniability, this can help give more direction and focus to a project.

GitHb Link to Project Scope

Missing Stuff? #

Read more articles about: engineering


No comments yet. Be the first to comment!

“Wisest are they who know they do not know.”

— Jostein Gaarder