0

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".

Michael
  • 821
  • 5
  • 12
  • @RobertHarvey I'm not wondering how to familiarize myself with it. I already know the code base extremely well. Sorry if I wasn't clear about that. What I'm wondering is how to go about writing a specifications document based on the existing codebase so that we can program against that document for the new codebase. – Michael Oct 03 '14 at 16:39

3 Answers3

4

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.

ecoologic
  • 245
  • 1
  • 11
2

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.

Anthony Ananich
  • 201
  • 2
  • 4
  • I'm going to edit my question for clarity, but in fact it's the 2nd one that I'm having issues with. I'm expected to make the Functional Requirements document...and I really have no idea how to go about it. I initially started writing the Technical specs, and our CTO asked me to stop and go back and make the equivalent of Functional Requirements first. It's something I've never had to do before and, given the size of the project and complexity of what it does, I'm not sure how to start. – Michael Oct 03 '14 at 16:57
  • I think that there is a misunderstanding between you and the CTO. For the success of the project Functional requirements is to be made by a person who is an expert in subject area. This way the software made will join strong skills of the programmer and the consumer. And I guess you are expert not in financial calculations, but in programming, right? – Anthony Ananich Oct 03 '14 at 17:01
  • Sadly, it's a pretty specific niche that the product fills (it's a small part of a much larger [in scope, not in bytes] project). We don't actually have an expert in it. I'm about the only person that really knows how the calculations work - and I only know from having to maintain the code. – Michael Oct 03 '14 at 17:03
  • 1
    Well, such a situation is also possible :) I do not want to upset you, but there is no silver bullet in this situation. Someone is to be an expert in the field just because knows more about it than anyone else. That does not mean that expert knows how to write functional requirements documents. In this case the most natural approach is to hire a consultant which could assist and guide through all the common pitfalls. – Anthony Ananich Oct 03 '14 at 17:12
0

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.

Chris Walton
  • 424
  • 3
  • 9