22

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.

Improve this question
0

5 Answers 5

Reset to default
23

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.

Improve this answer
9
  • 3
    It's difficult to be a champion when your boss is a blocker. Even if you start convincing him to not be a blocker, he's unlikely to make this a practice or one of your major responsibilities at a shop like this.
    – brian
    Feb 2, 2012 at 14:30
  • 7
    @brian: You still need to try. If you know of what needs to be done to improve things, it is your professional duty to bring them up and push for them to be done. If the company is not willing to accept your suggestions after being made aware of them, then it really isn't worth fighting a losing battle and you should just add to their turnover rate.
    – Bernard
    Feb 2, 2012 at 14:37
  • 2
    +1 This is the only way to get things moving in the right direction. It will mean a long term commitment though, and it's up to you whether you want to make that or not.
    – Michael K
    Feb 2, 2012 at 14:41
  • 5
    @brian Part of being a pro is establishing good practices for yourself. You have the power to decide how you're willing to work. Keeping a notebook is no different than having a computer in my mind, I simply can not reach my maximum productivity without one. A boss can certainly restrict how I share my notes and complain how long it takes me to finish a task, but that's a different level of problem than a boss not allocating project time for a good idea.
    – Steve Jackson
    Feb 2, 2012 at 14:42
  • 1
    @maple_shaft I didn't mean he should or should not, just that if he finds that he can't deal with being there for professional reasons, but has to stay for financial reasons (like, having a job :)), he'll have to work out a balance that doesn't cause him to really really hate it. (thanks for the heads up)
    – jcmeloni
    Feb 2, 2012 at 15:00
12

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.

Improve this answer
1
  • 1
    What bugs me the most is that the owner/ceo/whatever or the managers cannot see why the turnover rate is so high. Of course short-term goals are important, however, I wouldn't help but think that something is really wrong here. At the very least, it is a very good source of experience and like you said will help to teach a lot.
    – arin
    Feb 2, 2012 at 23:32
7

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.

Improve this answer
1
  • Good guess. Good suggestion, as well. In fact this is something I haven't thought of and could do. If, of course time can be found.
    – arin
    Feb 2, 2012 at 21:57
6

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)

Improve this answer
1
  • So far only in an informal manner. I'm thinking of going formal and then waiting to see what happens.
    – arin
    Feb 2, 2012 at 21:58
1

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.

Improve this answer

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