File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Jobs Discussion and the fly likes How to survive in a workplace without technical document Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Careers » Jobs Discussion
Bookmark "How to survive in a workplace without technical document" Watch "How to survive in a workplace without technical document" New topic

How to survive in a workplace without technical document

Wilson Oak

Joined: Apr 21, 2005
Posts: 19
hi, I have been joining a company for six months. The salary, company reputation and co-workers are nice. But one thing which makes me headaches is that the system is not fully documented. For instance, they don't have technical spec , ER diagram, functional requirement, nor user manual. what we have is just an out-of-dated data flow diagram.

The poor skilled manager believes that the diagrams are for high level only. if developers want to know the flow and detail, they should go read the code. The main problem is the code is 7-8 years ago and it is coded without any good design like OO or framework. Every time I am asked to fix bug, I have to spend 5-7 hrs to understand the flow, try to play around it and finally fix the bug which only spend me 10% of the time. Since the system is huge, there are so many part I don't know and it is hard for me to understand the system without document but reading the messy code. I am so stressed out as I spend at least 10 hrs everyday to try-and-fail the application flow in order to reproduce the problem.

Most of the team member knows that is a problem but they don't want to challenge the boss. I am think should I quit the job now and find a new one.

Anyone have similar situation? I would like to listen your story.

Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
This is a perfect opportunity for you to exceed your manager's expectations of you. I suggest that you start creating the system documentation that you feel is "missing." If you do a good job, it sounds like this would become a very valuable resource tool. Moreover, your relationship with your team will most likely improve in many ways as you demonstrate how you can handle challenges and improve systems. And your manager should appreciate this greatly.

Good luck!
Joe Harry
Ranch Hand

Joined: Sep 26, 2006
Posts: 10031

You are not alone in such a situation. I have faced similiar situations and I feel that this is the best opportunity to show pro-activeness. If something is not there, just you be the one to get started and create it. I have done that in the past and it opened up new opportunities for me.

SCJP 1.4, SCWCD 1.4 - Hints for you, Certified Scrum Master
Did a rm -R / to find out that I lost my entire Linux installation!
Joe Ess

Joined: Oct 29, 2001
Posts: 9188

Wilson Oak wrote: Every time I am asked to fix bug, I have to spend 5-7 hrs to understand the flow, try to play around it and finally fix the bug which only spend me 10% of the time.

Pretty typical maintenance programming from my experience. We use a wiki as a repository for our "tribal knowledge". It has everything we can think of: how to set up a developer work station, problem solving for known issues, procedures, user guide and so on. The standing order is, if you find something wrong in the wiki, you fix it.
My former manager was a big fan of refactoring to make life easier on us programmers. If one is working on some piece of functionality and can clean it up and make it easier to maintain with some redesign work, take some extra time and do so. I took over from him a year ago and we've become more aggressive, splitting huge ugly code base into several easier-to-maintain projects.
Like the others said, you have to take the lead on this. Make a business case on how documentation and refactoring can save you time and your boss money in the long run. That gives him something to brag about to his superiors, and will help keep you interested in your job.

[How To Ask Questions On JavaRanch]
Joachim Rohde
Ranch Hand

Joined: Nov 27, 2006
Posts: 430

Joe Ess wrote:Make a business case on how documentation and refactoring can save you time and your boss money in the long run.

Sad thing is, that some managers are so shortsighted, that even that won't work.
Some statements I heard when I complained several times about the lack of documentation, unit-tests and time to refactor:
- That's academic bullshit. In real life you don't do such stuff.
- We will do it later when we have time. But at the moment we really need this product to be shipped.
- Do it right in the first place.
- It doesn't matter how it looks like under the hood as long as the GUI is shiny.

As the others already stated you can try to become active yourself.

In my situation it was not only the documentation that was non-existing but there were a LOT of things going wrong (projects relied on the IDE for builds (everybody had to have the same setup), no CI-Server, no nightly builds, no bugtracking-system (except you call 'mails' a bugtracking system), no dependency management, no documentation, no unit test, no common programming style, etc.)
I first tried to write a build script which was independend from the IDE. The script had some flaws but it did its job. I also setted up a CI-Server which worked. My problem was: nobody cared.
My mistake was that I was not talking to my colleagues BEFORE I tried to change something.
Half a year later I gave it another try. I wrote a paper (roughly 8 pages) where I listed all the problems (ordered by severity) that our software development process (from my point of view) had, offered a solution (where possible with several alternatives) together with advantages and disadvantages and the expected effort. I printed this paper for every team member and asked them to read it and scheduled in the same time a meeting a week later where I wanted to discuss my paper.
That approach was much more successful because the majority of the team members were much more commited after this meeting due to the fact that they could express there own point of view and were not patronized by a single developer.

So a few tips which might work for you:
- talk with your other team members how you can improve your current situation and make sure that you are not the only one who wants to change something (if this should be the case: quit)
- try to get some time (like two hours a week) from your manager to just work on things which improve your situation (documentation, unit-test, refactoring, etc. Not for bug-fixing or new features)
- DO NOT work constantly 10 hours a day. It will break you one day and it won't be rewarded by anyone. (I came once out of a meeting which took four hours where a manager asked me afterwards what I was thinking about the results. Due to the fact that roughly 60% of the time was private chitchat (between my manager and our customer) I was a bit pissed and answered that the relevant details could have also been handled within an hour. "Are you not interested in the success of our product?", I was asked. The fact that I was programming 26-hours non-stop before this meeting to finish a feature we 'needed' to present to the customer, what my manager also knew, left me speechless (and quite angry)).
- If you agree with your co-workers on actions to be taken try to establish an environment of self-control. (We agreed e.g. on writing unit-test but one team member constantly broke existing tests without fixing them. In such a situation nothing will change if you are the only one pointing out that this needs to be fixed. But if several team members points out that the test needs to be fixed chances are much higher that this developer changes his behaviour in the long run)
- And if nothing helps / changes: quit!

I wrote several articles about my experience but they are only available in German. Just anyone is interested in it you can find it here:
chris webster

Joined: Mar 01, 2009
Posts: 2288

I'm a freelance Oracle developer, which means I'm used to starting at new sites where I don't know anything about the system and, all too often, neither do many of the local staff, so this sounds like some of the places I've worked over the years.

Lots of good advice above. I'd also emphasise a couple of points:

1. Don't feel you have to carry this burden alone. Talk to colleagues and managers to see if there's scope for working with them to improve things gradually, e.g. document/re-factor code as you work on it, so that it's a little easier for the next person who has to work on that particular part of the system. This may give you an opportunity to lead by example, by creating some useful good quality documentation, for example.

2. Be careful not to be a crusader. If your organisation really does not think there's anything wrong with the current situation, then the chances are that there are plenty of people around who contributed to the current situation, or who are happy to tolerate/pay for the extra work/stress it causes people like you, and they may not want anybody rocking the boat. So try to come up with some positive, pro-active steps you can take to improve things without costing the company any money. But if they're really not interested, don't push too hard: you can lead a horse to water, but you can't make him drink.

3. Look at how you can use existing tools to resolve some of these problems. For example, if you're on an Oracle database, Oracle's free SQL Data Modeler tool will reverse engineer the DDL from an existing database schema and draw you a reasonable ERD in a few minutes. There may be similar tools around to help with reverse engineering your particular database, and perhaps your class model, based on the existing system. If you manage to find something like this, make sure you share the results with your fellow developers, so people realise what you've done and hopefully how much work it's saving them.

Good luck.


No more Blub for me, thank you, Vicar.
Paul Clapham

Joined: Oct 14, 2005
Posts: 19973

You will find that sort of thing in almost every company which has a very large code base which has been developed over a period of years. And you should realize that you aren't going to get better documentation any time soon. It's not because the people in charge are lazy or evil (although both of those might be true) -- it's because producing documentation for a large system which can be quickly understood by an outsider is an almost impossible task. Even if your management were to commit to documenting the system, you wouldn't see the results for at least a couple of years.

So by all means continue improving the code base as you work on it. Document things as you find them out and put comments in the code. (Yes, the code is the ultimate documentation. If the documentation and the code are separate things, then people who modify the code will sometimes fail to modify the documentation appropriately. A few iterations of that and the documentation becomes useless.) And do keep on being an advocate for better practices, while at the same time accepting that the code base is never going to be much better than it is now.
Lee Kian Giap
Ranch Hand

Joined: Jan 23, 2008
Posts: 213
Similar situation, anyway team lead told me just follow as is every time I raise a question, because decision is from management level. For example, prepare Detailed Design Documentation by changing code into pseudo code.

Good Luck

Henry Wong

Joined: Sep 28, 2004
Posts: 20514

I'll give the counter argument... Yes, not having technical documentation is not a good thing. But that doesn't mean that management doesn't know or care about it.

It is unfortunate, but many companies are on a inflexible plan to their investors, or in reactive mode -- they have a drop-dead delivery schedule or need to satisfy the needs of clients. And these are caused by the need to "keep the lights on". So, documentation may be important to management -- it is just that there are way more important and pressing issues.

Having said that, companies in this mode for the long term do lead to a toxic environment, which leads to high turnover, and finally, to some sort of death spiral as knowledge of the product gets lost via the brain drain. This, of course, will be aggravated by the lack of technical documentation.

[EDIT: obviously, the counter argument is to try to explain why management seems to not value documentation, when they in fact do; there is no debate that not having documentation is a bad thing, so no argument there.]


Books: Java Threads, 3rd Edition, Jini in a Nutshell, and Java Gems (contributor)
I agree. Here's the link:
subject: How to survive in a workplace without technical document
It's not a secret anymore!