I was recently asked to analyse a project and write a little brief / specification, but the thing is that I don't really know how to do it.
At this point, I have extracted the main features, and destructed them in tiny tasks, thought about the architecture of the project, and which technology might suit best for the needs.
Do i have some other things to analyse ? How do you write this in a meaningful way ?
Thank you in advance Have a nice day!
I'm gonna go in the opposite direction of @michielsikma and say that it's very import to be very specific from the beginning on what you spec for a project, especially if it's paid work and your making a written contract.
Contracts are binding and a breach of a contract can be taken to court, usually small claims or whatever court in your country deals with lawsuits under $xxxx.
Do you need to say specifically "Home page will use a while loop, read from mysql table new_products and produce display a list of products with a sample image, price and link to view details" no, I don't think most people are expecting that. But the spec might look like:
Home page
List new products with image and details link
Quick link to Cart
Quick link to Sales email / form / phone number
etc...
The spec gets easier if theirs an approved design already created. Then you can break the design down into each page and the spec basically just reiterates what the design tells you to do.
Going back to above - if the spec says specifically what the app / site will do, and both of you sign it, it can be legally binding so make sure it says everything your responsible to do and if it's a big enough point, the stuff your not responsible for also - ie: "Hosting will be provided by AWS. Client will sign up for an account, give me the username / password. I will design and deploy the servers. A separate contract will need to be decided on for ongoing support"
With that, your putting it on them to choose the username / password, you build the server as you need it and when the project is done, your not on the hook to support it unless your getting paid.
So in the end - be very specific with what you'll build and won't build, but don't make it so fine grain that they need to be programmers to understand it.
We've been writing 'feature documents' as defined by Cucumber, github.com/cucumber/cucumber/wiki/Feature-Introdu…. This has been working extremely well as we are only trying to express the requirement, not use Cucumber to run testing. We've found that the terse and declarative way of summarizing a set of features has been helpful for all participants in the process, including QA testers, senior management and those asking for new work.
We keep these documents - simple text files - in the repository where the code that is being written, React.js components . Once you get the hang of it, a feature doc is quickly written.
Personally I think it's important not to over-spec at the beginning of a project, especially if it's very big. I also try not to get too bogged down worrying about implementation details. To me, they usually follow naturally from the team's skill set and the desired functionality.
Also, making minor adjustments to the spec will usually happen throughout a project, and there's always a chance of the budget being either relaxed or tightened.
My project specifications always start with a simple introduction about what it is we're building, what problem it's supposed to solve, and which target audience it's for. When we get to technical details, I care about what technical restrictions there are—what type of server environment we're planning on using, what programming languages we'll use (based on what the team knows), etc. Those are the absolute basics and usually won't change.
From there, I usually draft out the alpha releases, up to the MVP, followed by any number of subsequent releases. The further into the future a release is, the more vague they're allowed to be, since you never know what kind of data and feedback you'll gather. There's no point in specifying future versions exactly, when your customers might end up giving you a whole other picture.
To me, specific implementation details belong in the issue tracker, and not so much the spec. The spec contains a high level discussion of the project, the basic technical road map, and just enough information to give everybody a decent mental image of the mature product.