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)
- 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.
- 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?