Us developers and Engineers tend to get very excited when we get an idea for a new project. We can't seem to wait to jump in and starting building from the vague picture we have in our heads - only to stop halfway when we hit a roadblock or another idea pops into our minds.
In this series of posts I will attempt to go through the steps necessary to take the ideas we have and turn them into a finished project that we can be proud of.
This will be part 1 of the series discussing what might just be the most important part of the process...
the specification, also known by its shortened name: The Spec.
Why have a Spec
Now I hear you say,
Why do I need a spec for something that only I'm going to work on?
While it's tempting to dive right in and start coding away, hear me out first. The spec can serve many purposes during the development of any project - both professional and personal projects. Which we'll briefly go through:
It's a contract
The first of which is to be a kind of contract between yourself and well... yourself. Having a contract in place telling you what is expected from your app helps in motivating you to actually finish.
It assists in planning
Going from having a well thought out - and written down - spec to having a well thought out and detailed plan to completion is extremely easy. In fact, if the specification is thorough enough, it can even BE your plan of action.
It gives you a goal
When there is a detailed spec for your app, you'll know exactly when the development process is done - when it does what the spec says it should do. Knowing beforehand where you want to go gives you a great advantage in actually getting there.
It helps during development
Having a spec in place greatly reduces the cognitive load you have in almost every step of the development process. Whether it's designing workflows, UI layout, backend architecture or even testing and QA, having a spec serves as a reference that you can consult to ensure that you have all your bases covered.
Now I hope I've convinced you that getting a spec done before starting development is not only a good idea, but almost essential to getting a project done and into the hands of users. But how does one actually go about creating it?
How to create a basic spec
Now I'm not much of an expert when it comes to creating a well thought out and complete specification. In a professional environment, writing of specifications is mostly done by product and project managers. But I'll try to explain how to get a basic spec down as best I can and hopefully someone with more experience will write a comment correcting where I've made a mistake or give you some helpful tip - like this one on one of my previous posts.
The way I'm going to explain is by actually documenting the process of me coming up with a spec for the web-resume app I've been hammering on about since this post. Enjoy...
First step
Write down every little thing you can think of that the app should have. It doesn't have to be well thought out, just a basic list of things. Like this:
Web-Resume Features
- Sections for each part of the resume - like intro, experience, references, etc.
- Some sections should be able to contain multiple entries - example experience and education
- A way to share the resume by sending a link
- Filters to only show entries between certain dates or containing certain keywords
- A way to sort entries within sections and in general - by date for example
- A way to hide certain parts of the resume - like not showing a photo and references
- (Optional) a way to change colors and fonts
- Printer friendly version
- Download as PDF (or other format)
- Save different versions - example public, specific job, private
- (Optional for first version) monetize
As you can see, it's not pretty yet, nor well thought out in any way. As long as you write - or type - down everything you think your app should do and/or have.
Second step
Now that you have a list of features, it's time to organize. Start by sorting the items into similar or related features. I'll show you:
Content features
- Sections for each part of the resume - like intro, experience, references, etc.
- Some sections should be able to contain multiple entries - example experience and education
Filter and sort
- Filters to only show entries between certain dates or containing certain keywords
- A way to sort entries within sections and in general - by date for example
- A way to hide certain parts of the resume - like not showing a photo and references
Sharing and offline
- A way to share the resume by sending a link
- Printer friendly version
- Download as PDF (or other format)
- Save different versions - example public, specific job, private
Optional
- Change colors and fonts
- Monetize
There, we now have categories of features that we can expand on.
Third step
You've probably noticed that some of the features aren't really that specific, and some functionality might not even be mentioned yet. Lets change the descriptions in each feature category to be more specific and try to add more descriptions as we think of them:
Web-Resume will be an online platform to create and share one's resume. Following is a list of specific features that should be implemented on the release version of the platform:
Content
- The resume should be split up into different sections specified by the user
- A section consists of a title, default sort-order and entries
- A section could have either a single or multiple entries
- An entry could consist of text (including dates and numbers), an image or a data structure
- A user should be able to manually show/hide a section or entry
- The content should be formatted so that it could easily be printed
Filters
- There should be a way to enable filtering of the content
- A filter consists of a field name, a condition and a switch to determine whether to show entries that does not contain the field
- An entry should be filtered if it contains the field name and does not match the condition
- A filter condition could be one of the following types:
- date or number range
- contains (or does not contain) text
Sort
- There should be way to specify how both entries and sections are sorted
- The sort order setting should contain the field to be sorted by and whether to sort ascending or descending
Versions and Sharing
- There should be at least two versions of a resume - with more that can be specified by the user:
- A public uneditable version
- A private version which can be edited by an authenticated user
- Each version of the resume should have a unique URL
Optional features
- A way to download the resume as PDF (or other formats)
- A way to customize the appearance of the resume - colors and fonts
- There should be a strategy to monetize the app
As you can see that with each step, we iteratively improve and refine the vision of what the app is supposed to do and achieve for its user. We could go on further, but I think you got the point. The spec document isn't really set in stone. We'll iterate it further and make updates as we see fit and as the project develops. The important part is that we at least have a reference to start working from.
For those interested I've updated the README.md file of the web-resume github repo to the very basic spec that I've developed above.
That about covers what I wanted to say. If you liked this post, give it an upvote. Also please leave a comment below to share your own experiences with writing a spec for the apps you've worked on.
Expert tips are always welcome 😉