How do you create documentation when there is none?

Question

I have recently inherited a large, legacy system with a complex codebase that has a lack of documentation. I'm the sole internal developer embedded with the core users, taking some responsibility from an external contractor. While modules and functions are documented well enough, there is no documentation around the system itself. What it is, why it exists, how overall modules fit together.

This is a web-application, and an example of this is how it produces a page. This requires executing PHP that makes a call to the database that retrieves some XSLT with custom extensions, that is transformed (this process may happen many times), it may retrieve PHP from the database, however sometimes when retrieving PHP, it will retrieve a PHP stub, which indicates it actually needs to retrieve a PHP file from the file system.

While individual chunks of this process are captured, there is no documentation that takes a systemic or macro view of the world. So I've come in, and have begun writing what I've been able to figure out from emails to the current consultant, what I've been able to figure out from the code, and just raw determination.

Because of the importance of this system, the people I work with have its important that the system can be understood, so they are less reliant on a single person - be it me, the original developer or anyone. To be honest, I am happy with this, I'm secure in my own abilities, and if part of my task is to help mitigate the organisational risk if I was to disappear then thats fair. I also enjoy the task of unravelling a giant legacy system - its a giant puzzle.

However, the challenge is this - I need to produce some solid documentation around how the system works, both for me and whoever follows. While I have started to get a clear understanding, what I would like to know is what are the kinds of things a new developer would need to see to make sence of a legacy system that was new to them?

Similarly, knowing what needs to be written how would you tackle diving in, dissecting and documenting a large legacy codebase?

Answer 1

First, identify the purpose of the system. This should fit in an 'executive summary', no more than one or two paragraphs.

Second, describe the data sources and consumers. In short, master data originates from the product catalog, from user registrations, from 'fact files' such as states and zip codes, etc. Transaction data originates from the on-line users, those who are, for example, buying and paying for products. Further transaction data is entered by internal staff when making adjustments due to inventory, shipping, or payment problems. And so forth.

Third, describe 'module blocks' - table maintenance, order entry, order fulfillment, shipper selection, etc. This needs to be flowcharted - how one gets from the initial table population through the transaction entry to the closure of monthly and quarterly accounting cycles. Each of these should have user roles, some of which are create and edit, some of which are query only, and some of which consume summary reports.

From here one goes into gory details: schema definition, form layouts, print layouts, etc. More than likely the documentation you need to focus on here is what is not 'obvious', such as, for example, pulling PHP fragments from the database. These unusual practices should be documented early in your efforts.

Answer 2

This is a bottom-up approach where you need a top-down approach, but it should help if you combine it with other answers:

When you look at a part of the system for the first time, you're as big a newb as anybody. You don't know what you're looking at, but you know what questions you have (WTF if nothing else) and where you would like to see some answers. When you think you've got an answer, document it as you would have wanted it documented before. Actually, you might want to start documenting immediately by putting in the questions before you have answers. And, as you go along, you're apt to mix your answers with questions. ("This code seems to ..., but is anything actually using it?")

This works for any kind of documenting (including your own code that was not documented because, as you wrote it, the code seemed self-explanatory). Try to remember what it was like when you understood nothing so the next person (or you, after you've forgotten it all) can glance at your documentation and understand as quickly as possible.

And when you encounter code you documented earlier, and find either that it makes no sense to you now or doesn't answer one or two key questions, fix it up as soon as you can figure it out again or find the answers.