I inherited a project that I’ve been maintaining for approximately a year now. The project primarily revolves around performing various financial calculations for the end user. It’s roughly 100,000 lines of spaghetti code held together with duct tape and gumption. I’ve been slowly going through and refactoring the code as I have to make changes to it, and adding inline comments where helpful, but there’s no formal documentation.
I’ve been tasks with rewriting the software on our company’s new platform (I know, the worst decision a person can ever make is a complete rewrite, but in this case it’s necessary, as the entire architecture and framework involved is changing). As the first step of this, I need to come up with a set of functional requirements. However, I’m at something of a loss on where to start and how to go about it. The scope of it is just so enormous that I’m not even sure where to begin.
Has anyone else had a similar experience? Where did you start with the documentation for the new project? Are there any resources out there I could consult? I could write the technical specifications of it today without an issue, but I’ve never before had to write functional requirements.
I know it’s not normally part of the developer’s responsibility to write functional requirements – someone in the business department should do this. However, it was apparently decided I was the best person for the job as to most of the people in our business department, the way it works is just “magic”.
1
How old is your app?
Almost two years ago I inherited a similar situation in a 5 years old app and we keep calm and carry on, small, small continuous improvements.
If I could, I would start from the client and the final user. I’d be gathering requirements in the same way as a new project. It’s likely the user / client needs have changed or they have new ideas. The app very likely has failed functionality that I don’t need to re-implement. I’d be using it as a mere “mockup” example.
In this way I have the advantage of actually showing a product to people who already know the problem. And understanding the code I can ask the right question about the behavior.
Technology also improved and it might offer another possible point of view on the meaning of your app.
That’s what I would do if I were so lucky to have the chance to start from scratch.
I started programming in 1999 and I provide software outsourcing services since 2009 as my own business. During this time I participated to over 300 software engineering projects for over 100 customers in different countries.
The good news are that the only one company with good specifications I’ve seen is NASA. The others usually have a specifications which is better than nothing.
First of all there are several types of documents involved in software development lifecycle:
- Business Plan – this document gives explanation how much will the software bring (or save), how much resources it will need to be created, how much is the cost of ownership.
- Functional Requirements – this is a more particular document which describes in detail what problems should the software be able to solve. This document is usually created by a person who knows the business well enough, and in your case that should be someone familiar with financial calculations.
- Technical Specification – The document created by CTO or Architect or experienced senior IT employee etc. It describes the approach to the problem and answers the question “How will we make it”.
Note: This is not the complete list, it’s more closer to minimal required set.
So I guess you are trying to make the last one of these docs without having the first two. I’d suggest to get at least a functional requirements first and based on this document you’ll be able to make a Technical Specification for the solution based on the new platform.
4
Practical Software Requirements is out of print, but if you can get hold of it, you might find it useful. It is not written from the point of view of your problem, but it does suggest approaches that result in functional requirements that have a very high signal/noise ratio, and starts from the bottom up to some degree.
in addition Volere provide a variety of resources – templates, documents, and consultancy – to aid in documenting and comprehending requirements. I found their templates very useful, though some discrimination on choice of templates is required.
All the usual disclaimers apply: I have no involvement with either of the above sources, but have found them useful.