A System for Analyzing Systems [Part 2]

This is the second part of an (awesomely epic) series on how to analyze a software system quickly, click here to view Part 1.

So now you (having the right attitude and documenting everything) have viewed the main nouns (data) and verbs (use cases, workflows).  What do you do next? Profit?

#3 Find integration points and environmental concerns

It is important to understand the system within its software ecosystem – find the system edges:

• Make a list of the technologies used (again – avoid judgment)
• Make a list of the integration points (other systems, off the shelf products, web service apis, manual steps in overall process)
• Look at dll references, build files, web references, configuration files, database connection strings, etc.
• Draw a simple sketch of the application within its context with others

#4 Read some code

This is normally where developers start – reading semi-colons.  But maintain some discipline:

• Make a simple outline of the project structure and main namespaces and entry points. Input, processing, output.
• Try to not go down every rabbit hole too quickly – add to your WTH list liberally and then circle back.
• Guided by what you know already dive in based on what makes sense – read the billing module, the calculation piece, the ranking algorithm, or the integration with Facebook.
• Document system conventions, code conventions, and architecture. The build order can be useful and painfully revealing here – on larger projects I break out ndepend to see the overall structure.

#5 Read some documentation

If the project has some artifacts now is a good time to read them. Most people will read them earlier in the process but since documentation is a record of what was the truth during a time in which the truth was still being figured out when people had time to do such things I’ve grown untrusting of it until I know what is what in the application. Project documents are fascinating in that they provide historical clues to design decisions, project status, pressure, and onetime events like data conversions and client meetings that affect the system in the future. Read up and take notes. Be aware that some pieces of documentation are position papers and do not represent the current reality.

#6 Talk to some people

Armed with nouns, verbs, and a basic understanding of the code go get your questions answered by someone on the project (if they will return your calls). A few tips for this process if a developer is handing off to you:

Realize that when a developer hands off they will do two things:

• Blow off steam (I really didn’t want to do this but that freakshow client forced us to)
• Play defense / apologize (I was under pressure so just hacked this up)

Let this happen, avoid judgment and be friendly and helpful.

#8 Identify the Win Condition

By this stage in the game you should know the “win condition” of the system – when it works how it provides value to a customer.  Examples would be:

• “Allows users to find out about flight delays before other airlines, saving them time and allowing them an advantage against other travelers in a cancellation scenario” (FlightCaster)
• “Provide an easy to use way to update online ads across multiple platforms based on your inventory” (Tentail)
• “Allows users to find out about current events much faster, trade cat pictures, and waste half of their life” (Twitter)

#8 Wrapping up

So now you have your document with just Facts and Questions having hopefully whittled down your WTH list. Polish up your facts and add a summary statement and the application “win condition” to the top and you are done:

EasyTrack is a web-based accounting system used by small businesses that is built on ASP.NET Web forms with a SQL Server 2005 database. It integrates with Quickbooks, exports transactions as csv, and has a web service api for 3rd party integration. It syncs nightly with a client customization of an older version that uses the same database but has a non-web frontend. It works in Internet Explorer. Its niche is being an easy to use tracking system for a discrete set of common accounting tasks that are harder to do with larger systems.