How-to convince company to start documenting for legacy software

Question

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at all) documentation.

Not only do the developers in the company struggle with the lack of documentation but also there is a high amount of turnover, causing everyone to lose their time. This is because experienced developers have left the company and there is less and less resources to communicate/brain storm with.

Without getting into too much detail, I have suggested to the previous manager that there needs to be some sort of documentation (at least an Architecture document) that outlines the product. I also suggested using JavaDoc and other automatic documentation tools. These suggestions were responded to by slight smiles and statements of the sort "We do not have enough time", "We need short-term improvements right now" and even "The code itself should be the documentation" from the programmers themselves.

I have already wasted enough time trying to find out if what I needed per requirement/bug had existed in this big (really) code base. I am looking for any suggestions that you might give regarding the need of documentation. Or, rather, if this is a lost case for this legacy system or organization.

Answer 1

I feel your pain. I've been in this exact position before.

My suggestion is to lead by example. Start a wiki or document and start making notes. Make repeated references to this document you're putting together. If someone asks you a question, make a show of looking at the document for the answer first. If the question isn't there, add it to the section of unanswered questions. As it grows, share it with everyone. Add time to document to your maintenance tasks.

You have to grow this organically. It needs a champion. I'm not aware of any developer-driven argument that will make a company that doesn't care about documentation suddenly flip that switch. Once it's in place, everyone will wonder how they got by without it. Sadly, once you move on, it will probably become obsolete and die.

Answer 2

These kinds of shops are horrible to work for. I pity them as I would a wounded animal that is dying.

Old technology, overflowing with technical debt, constantly putting out fires, an ever increasingly disatisfied, angry and sometimes vendor-locked customer base... sound familiar?

You know that slight smile that you get from the overstressed manager that probably has a lower life expectancy because of the mess he has to deal with everyday? That is the smile of somebody who has had almost 10 years of programmers new to the company telling him exactly the same thing. Don't think for a second that with all the turnover that there hasn't been at least a handful of other developers all who came to the same conclusion.

They aren't there anymore because they failed to change things for the better and got frustrated and left like everbody else. But by all means try to do this on your own, we tend to learn the most from our failures, not our successes.

They are sufferring under the quagmire of their self inflicted wounds and eventually when their customers find a way out or a better competitor comes along this place won't be there anymore.

If I were you I would start looking. I have no patience for these kinds of software shops anymore.

Answer 3

Aside from pushing for documentation (which is important), I would also suggest pushing for tests to be written (if they haven't been already and I'm willing to bet they haven't been). As Michael C. Feathers talks about in his book Working Effectively With Legacy Code, tests are a good way to deal with the cluttered code in a legacy application. Write tests that will help you to understand how certain parts of the code are supposed to work. This in turn will help you to document the architecture of the application as you should gain a better understanding of the code, as well as help with any refactoring you will need to do.

Good luck! I feel your pain as well.

Answer 4

You probably have the crux of why they have a high turnover in your post. You have already raised your concerns with management, make sure you have done so in a formal way pointing out the business reasons for documentation (reduced support costs and wasted resources in trying to figure out the code).

If you have raised your concerns in the correct way and management still ignore you then your choices are a)suck it up b) Look for a new job (I would recomend b)

Answer 5

I don't think you really need your boss's permission to do some documentation. The most obvious place to start your documentation is the code.

You don't have to launch an all-out documentation-only attack. Just focus on incorporating documentation as part of your daily work. When you work on a method without JavaDoc comments, add them. When you add something convoluted but necessary, add a few comments to explain. And of course make sure that any new code or features you add are fully documented.

Doing this to the code you're already working on won't add more than a couple of minutes to any given task, and will gradually improve the overall quality of the code.