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 😉
Us always appreciate n give opportunity to rise new ideas and programming so nice post I like it.plz upvote I m from nepal
Thank u
make a post and show us some pictures from Nepal please!
This post was very informative thank you for sharing
you have my upvote
Thank you
Very detailed, like it. :)
Thank you
That's absolutely true and well it might not be useful now, but later when you try to scale your app, definitely you are gonna need it.
I happen to think that having a spec is useful even in the very beginning...
and during development...
and testing...
heck even when the project is running out in the wild having the spec available could be useful.
What I'm trying to say is, the spec is always useful.
What I wanted to say is that, sometimes you do not know what exactly your idea is, thus you do not have anything to write upfront. Let your idea to start, like a bit of coding and the spec along with it. It will not only help in planning better but it will give enough time to switch between spec and development. Whenever you are stuck in development take your time, write spec. That's what I usually do.
I see
Thanks for your post. I'm just getting started trying to learn programming, and planning (in anything) has always been a problem for me. I just tend to take-off. I'm guessing you can save yourself a lot of time, and many headaches by planning things out first.
You certainly can.
When just starting out though I would suggest you try and work through some sort of predefined and structured set of exercises - like a tutorial series or course - just so you can get the hang of all the moving parts. Try to at least change parts of the code in the tutorial so it better matches what you're trying to achieve.
As you get more comfortable with programming, you will need to rely on following tutorials less and less.
Good luck.
Thanks.
Might be interesting also thinking about persistency in means of what to store how long, how secure and where.
That really is more focused on the technical specifications/design. It might be valuable to think about if it's an important part of the functionality of your project. But for this specific project, the way that data is stored really isn't a critical part of how the app functions from a user's perspective.
But don't worry, I'll be talking about data storage and backend architecture - or possible lack thereof - in a future post in this series. 😉
Nice article, thanks for sharing.
I'm glad I caught the first one.
I'm following and eagerly anticipating the next in the series
Thank you very much @spidersprog.
I am planning to put links to this post in the next post in this series anyway - and in every one following - so needing to catch the first shouldn't need to be an issue.
I'll try to get the next one done as soon as I can, but it takes a while for me to get an article done between work, gathering all my thoughts together, actually working on the app and work...
Did I mention work twice... 😅
Thanks again.