I’ve been asked by my boss to write a specification for a new application module, which is alien territory for me. I’m usually given specs to work from by others, but the way they approach it goes against how I initially plan an application. I tend prototype and write notes about the application as I go along. They’re more technical too, dealing with specific functional elements (validation, error handling, etc).
How do other developers tend to approach specifications? My boss needs an idea of how the application will work, so would it be considered a spec or a pitch?
I’m dealing with PHP programming language, although I’d appreciate any advice regardless of background.
My idea is to keep things simple that even a lay man would understand, unless of course domain related business logic that only we know about needs to be implemented.
It depends if your boss is looking for a functional or technical specification.
A functional spec describes how something will work from an end user perspective. I like to use PowerPoint to create mockups with little embedded notes. A picture is worth 1000 words.
A technical spec describes how a feature will work internally, and is usually written for programmers. This will include API documentation and implementation notes.
As other have mentioned, user stories and other Agile practices should be used in conjuction with some minimal documentation.