Writing specification documents


The practise of software design, even the addition of a small to medium size feature to a web interface should start with deep and calculated thinking. This thinking needs dedicated time.

Defining a summary

It's important to begin with a clear and to the point summary of the project. You and your team are not the only people that my read this document. Upper management might dip in to understand what the team are working on. A week written summary should provide an understanding of the project.

Explore solutions

The majority of time should be spent exploring options and solutions. If you think you have the correct solution try and find a few out of the box solutions which could stop you from arriving at a local maximum solution.

Once you have explored options and have a proposed solution. It is time to reach approval from all stakeholders. This allows for early correction and keeps everyone on the same page.

Breaking down into tasks

Once you have approval. It's time to start breaking down the project into tasks. I suggest starting with a list of things you will need to do. Once you have the top level steps listed. Convert that list into headings and provide a brief description for the step. Under the description start to list smaller atomic tasks. Once you have achieved this. Convert the task lists into headings and provide a small description.

You have now broken down the project into epics with nested tasks. You can copy these headings and descriptions into your project management tool.

Assigning success criteria

Without success criteria there is no way to check if a project was successfully. You should set a few measurable objectives. Be ambitious but realistic. Set a date in the future to review these metrics and report back to the stakeholders if the project hit or missed it's success criteria.

By setting the success criteria at the planning stage. This gives you and the team time to set up means of measuring the metrics. For example adding analytics events to the right places during development instead of retrospectively.

If a project is unsuccessful, your should investigate why and maybe even suggest remove the feature as all code incurs a maintainance burden on the team.

Living document

The specification document is not complete once it reaches approval. Keep the document alive with challenges, decisions and evolution. At any point during the project you may be vacant from the project. For example, you could be reassigned, become sick or leave the company. The team will need quickly catch up with your knowledge of the project. If the spec document has been kept up to date that will be a great help.

Turning specs into articles

Once a project has been completed you should be able to take the content from the document and with some light restructuring turn it into blog post about the feature. This helps to advertise the feature and attract talent to the by demonstrating the working process within the team.