How should I document an existing system

Question

Hi there, I've just started at a new job with sole responsibility for a large(ish) financial application. It's got about 800 stored procedures, 120 SQL server tables and 18 .net projects with approx 1200 code files. And no documentation other than line comments in the code.

As I mend bugs and make ad hoc to the data I want to document what I find.

The main thing I'm interested in is describing what occurs after the user does someting (e.g. presses a button to upload) How the data is changed and what methods/procedures are called to make that change. In that way if a bug is noticed by the users later on I can see the path(s) taken through the code/tables quickly. What should I use to document this. Is this a UML use case or a Sequence diagram? Or something else entirely?

Any thoughts welcome. Richard

Answer 1

My vote would be for using UML. It's probably going to take more than one diagram to get your point across (documenting white box/black box functionality, user intent, class layout, etc)...but it'll be tremendously helpful to both you (in the short term) and other developers (longer term...they'll better understand the architecture and design intent).

Answer 2

"What should I use to document this. Is this a UML use case or a Sequence diagram? "

Both.

The user's experience is a use case. Narratives and text will do to describe the user's interactions. You can use state charts or sequence diagrams to provide details, but it's usually a waste of time. Words will do for this.

The implementation can be a sequence diagram. Often, this isn't enough. You'll probably need some class diagram to describe the data model. Indeed, you often need two level of class diagrams -- a conceptual level and a logical level.

You'll also want a component diagram showing all the pieces and parts and where everything fits together.

Finally, you'll want to look at the "4+1" views (Logical, Process, Component, Deployment and Use Case) as a way to segregate the documentation so it doesn't become a random pile of notes.

Answer 3

A sequence diagram describes the flow of a process through the system. A use case diagram describes the process of a user interacting with a system.

In my opinion, sequence diagrams are hard to maintain unless you have a tool to generate them for you. Things change too fast, especially in a large system, for the sequence diagrams to stay up to date for very long.

In a case like yours, I'd probably start documenting from the bottom up. What purpose does each of the tables serve? Next, document the stored procedures.

Alternatively, if the system has a ton of old code in it that's no longer used, I'd start at the entry points in the application and work my way through from each of them, documenting the things that are actually used, and putting the stuff that's not used on my hit list for deletion at some point in the future.

Answer 4

You might find Doxygen useful for documenting the code structure of the .NET projects. The Doxygen website links to HyperSQL as well as several other documentation tools. This doesn't help with your UML/sequence question, but the automatically generated documentation can make the job simpler if you take Rafe's approach to document from the bottom up.