Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This question already has an answer here:

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?

share|improve this question

marked as duplicate by gnat, Kilian Foth, GlenH7, BЈовић, Dan Pichelman Jul 26 '13 at 16:21

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

1  
Possible duplicate questions, that I don't think are applicable to this question: programmers.stackexchange.com/questions/163455/… - This is a question of how to deal with poorly documented code. The codebase I have has documentation within code, but documentation around the system. programmers.stackexchange.com/questions/155488/… - Again, this is about dealing with code, not with a lack of systems documentation. –  Lego Stormtroopr Jul 26 '13 at 3:02
2  
Not a duplicate, but possibly of interest - see I've inherited 200K lines of spaghetti code — what now? –  Dan Pichelman Jul 26 '13 at 3:02
add comment

2 Answers

up vote 4 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.