Welcome to the Planning Portal at Metabolism of Cities! This page lists tasks and instructions to assist with one of the most important and foundational aspects of our platform: the planning process. While there are many aspects around planning, for now we will focus here on the task of "specification writing". This is a fundamental task that should preface the development of any new module, sub-site, tool, or any significant section on our website. A technical specification is a document that outlines the feature in question, why it is being built, who it is for, how it should work, etc.
A well-written specification is of great benefit to our programming team. Programming skills and time are limited within our group, and by writing up these specifications we can ensure that actual coding time is reduced and we allow programmers to free up their time and focus on coding rather than planning and discussing. Lastly, good specifications increase the chances that tools and systems are developed with the right structure and functionalities from the start, rather than having to going through multiple iterations of build-test-build.
Assisting with the development of website specifications is one of the most important contributions to the web development process people without requiring programming skills can make.
How to write a technical specification? There is no single, set format, but this post lists a few key ingredients. For our purposes, these are the most important pieces to include:
- Objectives: what is this project trying to achieve? Why is that important?
- Audience: who would be using this new feature/tool/site?
- Structure: describe in broad terms what this tool should do and look like. How would it fit in with the existing website? What are the most important elements?
- Functional specification: this should be a more detailed overview of all the different functionalities that should be included. What kind of features should this tool have? Using "user stories" is useful.
- Examples and references: what are existing websites or tools that do something similar? Highlight any specific features or elements that you consider inspirational (or that should be avoided).
- Non-functional specification: include other requirements that are not functionalities per se, but that should still be taken into account - such as design ideas you might have.
Where appropriate, include drawings, mockups, or any other kind of visual in your specification. This specification might be developed by a single person but it should subsequently be discussed and reviewed by multiple stakeholders. Writing such a specification will take some time, some back-and-forth, and it will lead to some discussion. And that is exactly what we hope to get out of it before starting the development process.