How should I document a multi-tier application?

Question

I have to create a documentation structure for a legacy application, and I'm not sure of how to organize it. Documentation goals:

• List of use-Cases
• Program flow for each of the use cases. (Flow-chart of all the logical steps the code does for a particular use-case).
• As far as possible explanations of why a certain business/code logic is followed.
• Documentation format if possible should not require installing a new tool, and at best be readable in Word or PDF Format (so that the business types can check it easily).
• Some questions that should be answerable using the documentation: "What business logic does the code execute for a given use case?";"Is this code redundant elsewhere in the application?"; "If I change this code, what Use-Cases are affected?";

Application characteristics: (it's generally a bit messy, with presentation and business logic slightly mixed in almost every layer)

• Presentation in .NET Web Forms using WebControls (GridViews, ObjectDataSource, Reports) and JavaScript(jQuery, jQuery-ui) in *.aspx pages
• Server-Side Code in C# in the *.aspx.cs to handle post-back events.
• C# Code-Pages and a Seperate Project integrated into the WebApplication supplying Business Logic as part of the Web-Application
• SQL Server for data persistence (Master-Data DB, Data Staging DB)
• Views including some data from others Servers
• C# CLR assemblies for business logic deployed on the SQL Server, and some minor SQL Stored Procedures/Triggers
• A File structure on the same server as the SQL DB that handles archiving, data-import from files.
• File interface to SAP (that I don't fully understand yet).

So far... I've started documenting in Word. I have a separate Word file for the Front-End and the Database/File Structure. I begin each File with Use-Cases (user-initiated are in the front-end, scheduled jobs in the Database file), followed by the code structure. Each use case has a hyperlink to a flowchart/explanation of the code that first gets executed, which has a hyperlink to the flowchart/explanation of the code that next gets executed, etc... I do this so that each part of code is documented only once, and that other parts of code documentation can link to it if they execute it in the application.

Problems:

• I can't navigate backwards from hyperlinks (i.e. I can't answer the question: "If I change this code, what Use-Cases are affected." I can only go from Use-Case to Code, not the other way around.)
• The word document already feels clunky and messy after I've barely started to write stuff into it.

Question: How can I document this multi-tier application without making a great mess?

Answer 1

A well-organized Wiki would be my suggestion. I have used Atlassian Confluence in the past. I believe this is well worth the time spent, especially from the company's perspective. It does take a lot of time and effort to create, maintain and enforce documentation standards, but after you've had a few senior developers leave a mess of legacy code, you'll be glad you did.

A wiki can be organized like a file folder and can even create index pages for you to allow you create all the linking you need. Also, the searching in Atlassian is excellent.

For users that are not savvy enough to create pages, just have them create nice Word docs, then import them into the Wiki.

The main thing is to have a well defined structure and enforce documentation standards. This must have complete buy-in from management to work. I maintained a wiki for my previous group and it became essential to daily operations because I kept it clean and organized.

Answer 2

In my experience this big efforts in documentation are a waste of time. Its better to use this time adding new features to the application and value to your business or refactoring the messy parts of the code, a word document usually don't solve any problem in a software application.

I'm not saying that documenting its not necessary or its nor a good thing, but documentation an traceability (the ability to go from code to the user history/use case) must be done in a day to day basis in a project not in a big effort when probably its to late.

Anyway, i prefer to use some shared tool like a wiki, when you are building the next feature for your application write the documentation that you think that can save time for the next guy and only for that part of the application. In this way, you are adding valuable documentation step by step and your (and all the team) learn the habit of revise the documentation in each task. With big documentation efforts is very usual that the final documentation its of little value and sooner than you think its completely useless and out of date because the team don't have the habit of modify the documentation with each new change in the application.

About traceability, use a ticketing tool (like jira, trac, if you use .net microsoft have good tools for this) integrated with your VCS and in each commit include the number of the ticket this commit its related to. Again its a day to day practice that gives you without effort REAL traceability, traceability in a wiki on in a word document its only a illusion.