10

We're in a bad situation of having very little documentation on customization our past workers made to a business critical system. Lots of changes were done to Crystal Reports, database entities, and proprietary configuration/programming files for our ERP software.

The current documentation generally reads something like this:

This program is run before invoicing. Known bugs: none.

Run this program after installing software X.

Changed the following fields in this report: (with no explanation of how or why)

Our IT shop is small, and in the case of the ERP software, most work was lumped on one person (that's me now) so no one else here knows what all we did. The IT and accounting department know bits and pieces (occasionally quite helpful ones) but it's not enough.

Another problem is our Accounting department seems to think we're well documented. It's true that we kept lots of records of what went wrong, but very little explains what (if anything) was done to fix these problems. We have hundreds of papers explaining bugs, but the documents explaining changes (as shown above) are almost useless.

How can I go about documenting past changes when I don't know what all was done? I can start with documenting what we've changed: Files, database tables ect which we need to have for the system to work. I can also document what we do; when reports are run, why people were told to use X report/program. But when one of these customized things has a problem, I'm always back to square one.

How can I proactively document this stuff for myself and others?

Improve this question

7 Answers 7

Reset to default
13

I think this is a futile exercise. If it works it works, if it doesn't work, you have to fix it.

The best way to document old stuff is as you work on it, document what you are doing and explain the business logic (which I assume was not documented). This will be a big help for any new developer.

Speaking of documenting old code/things, someone had to own it. Lets assume this is your current manager. He/she might not have full technical knowledge of it but will know what changes were made. In that case, it is not your job. May be the manager can write something about it what changes were made. That would be helpful to keep as history. If problem like that arise you can dig into those areas, that might be very helpful to you. But going into the code and document the changes is pretty useless IMO and probably impossible.

Improve this answer
1
  • 3
    Yup, this another one for the Boy Scout Rule, but I'd also add - Document in your source repository, not in a wiki. The closer your documentation is to your source code (by JavaDoc or XML in Visual Studio for example) the more likely it is to be kept up to date, plus it gets versioned along with your code. I'm not the only one who like rst and sphinx for keeping writing documentation close to the code.
    – Mark Booth
    Feb 24, 2012 at 18:56
10

Abandon your effort to document changes.

Instead, start documenting what currently works, and how. Keep that documentation up to date and current as you make changes in the future.

Improve this answer
8

Do you have source control?

Can you work out what has changed from that?

If so, then you may be able to map that to business changes, whether new features or bug fixes.

Is it possible to resurrect an old developers mailbox? (not sure if this is viable with privacy concerns or not). There may be lots of information to be gained by trawling through there.

Improve this answer
1
  • Source control was used...really poorly. No helpful commit messages, the SVN was mostly used as a backup. I can see what files were added when (very roughly) but that's about it. Our customizations are all in their own folder (changed reports, form changes ect) but that's the best I have. Diff isn't any help since everything exists as a compiled file except our SQL statements.
    – Ben Brocka
    Feb 24, 2012 at 15:06
5

First things first. Where are you storing your documentation? If you haven't already, set up a wiki. I prefer dokuwiki myself, and there is even a prebuilt vm, if you are so inclined.

This provides some important features:

  • Docs can be accessed anywhere on the company lan (installing on new computer...)
  • All docs are in one place
  • All docs are searchable
  • You can collaborate (new colleague, users of the software)

Now, if your documentation is in paper form then I wish you the best. If you have word docs, build an import script.

Finally, just use the stuff. Whenever you need to install something, put notes in the wiki. If you hit an edge case, put it in the wiki. This is where collaboration can shine, since you get other people to do the work for you.

Moving on to more specific documentation, if you need to work with the source for various projects, make sure you have a proper development environment set up! For a checklist of stuff you should have:

Finally, because documentation can be boring, make it a game. Give yourself "points" for each item in your checklist, periodically checking your "score". It's a good way to see what you've accomplished, and how well. It also maps out where you need to go next.

Look at this as an opportunity to learn many things about how to set up a proper dev environment, and don't be afraid to try things and move on. Find something you like and migrate the environment over so that things are better. Approach this as a project where you are looking to build the best solution.

Edit:

As per rig's comment below, another useful thing to do is create diagrams of the source code. Freecode has stuff, and this article lists some for popular languages.

Improve this answer
3
  • One thing you didn't mention (which I never worked with ERB projects) that I've done in the past with .NET and Java is using a reverse engineering tool to produce class diagrams and sequence diagrams automatically. They were quite helpful for this. Is there anything like that in this case?
    – Rig
    Feb 24, 2012 at 15:59
  • +1, great info, can you tel me about dokuwiki ?
    – PresleyDias
    Feb 24, 2012 at 17:04
  • @PresleyDias besides what's in the link? Check the feature list. Our setup uses the arctic template so the wiki acts as a mini CMS. If you are on a debian system, install manually instead of using apt-get! Debian uses non standard locations, which makes it a pain to manage.
    – Spencer Rathbun
    Feb 24, 2012 at 17:12
2

The best you can do is document everything you do know and ask around the company to document anything that others know as well. I suggest centralizing the documentation in a wiki or something similar so that everyone has access to the most up-to-date documentation.

You cannot document something you don't know, so either you attempt to learn and discover why something was done or you just leave it undocumented. This is why company's need to take greater care to document things while those that know are still employed there.

If you are attempting to document any code that you do not understand, I suggest you write unit tests to test the functionality. This way you will better understand what the code does and the tests themselves can serve as documentation.

Good luck!

Improve this answer
1
  • Unfortunately it's not a traditional programming set up...mostly reports and GUI changes with some weird, proprietary language files used to change how the program acts.
    – Ben Brocka
    Feb 24, 2012 at 15:00
2

When I try to document something that someone else who's no longer with the project or the company did, I always start the attitude of: This is a blackbox to everyone including me until I need to change something or explain it to someone else.

The reason that this project is in the documentation shape you have found it in is because documentation of any work is somewhat secondary to getting it running. So document what you change and if you have figured out what the particular field in the database and what particular block of code does, if for noone else's benefit but your own.

Improve this answer
1

You could write automated exploratory tests. These have several advantages :

  • You learn how the system works as you write them

  • They serve as executable documentation for later

  • If you run them on a regular or even continuous basis, they provide a nice security net to detect when changes break something or when they need to be updated

I don't know if it is feasible to write that kind of tests in your particular environment though.

Improve this answer

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