How to document an existing system?

[em1x3em]

NOTE: I apologize if this is an inappropriate post for this forum... i browsed all of them and this one seemed best. Thanks!

I just got a job where my job will be to dismantle an existing system and document it at many levels. Are there any books written on how to do this or best practices when attempting this?

I'm interested in how to create documentation for all levels of understanding... (developers, department heads, users, etc)

The system is comprised mostly of SQL Server databases (tables, views, and stored procedures), COM/DCOM objects written in VB6 and ASP pages.

Thanks!

 

[jmeckley]

wow, this is quite a project.

I would start by reviewing the code at a macro level. what layers are present and how do they interact with each other. nothing too specific, just enough to have a general idea of what's going on.

I would also try to talk to the previous developer(s). Hopefully they are either still working their, or willing to meet you for lunch or something. be prepared with questions you have about the code, db structure.

with this information review the code a second time this time digging deeper into each object. what are the objects/members, how to interact.

after this I would begin to comment the code for other developers.

For a user training manual I would take each screen in the system and work through the layers vertically. Then document how the features of each screen.

good luck

Jason Meckley
Programmer
Specialty Bakers, Inc.

 

[stevexff]

Suggest you check out Enterprise Architect

http://www.sparxsystems.com.au

Aside from its excellent UML capabilities, it also has a number of filters that allow reverse engineering by importing code into models (both code and database tables). You can get a 30-day trial for free. And the real product is remarkably cheap too, probably considerably less than your day rate. You should be able to slurp the code in and then just drop the classes onto diagrams.

You can also export to RTF and HTML versions to produce your docs.

Steve

[small]"Every program can be reduced by one instruction, and every program has at least one bug. Therefore, any program can be reduced to one instruction which doesn't work." (Object:erlDesignPatterns)[/small]

 

[DonQuichote]

Maybe the famoos reengineering handbook is of any help. Just do a net search for it.

+++ Despite being wrong in every important aspect, that is a very good analogy +++
Hex (in Darwin's Watch)

 

[cpjust]

What is the purpose of this project? i.e. what will they do with it once it's documented?
Knowing the reasoning behind the project would help give you (and us) a bit more direction. Also, did they give you a specific amount of time to finish documenting it? Is it a full-time project, or something for you to do when you aren't busy with other things?

 

[em1x3em]

Thanks for all the replies! cpjust the purpose of documenting it is to be able to support it and understand its operation more effectively and ultimately i think they are going to rewrite it in another language.

The documentation they have at this point is pretty sparse and I would like to create documentation of all levels.

I was just wondering if there is a best practices way on how to document while dismantling a system. :-D

jmeckley I'm not going to get that lucky! ha ha I get one week (this week) with the last support person and I'll have unlimited access to one of its power users... so its all me.

P.S. Its a large corporation so I'm not sure what they usually require as far as like UML documents... use cases, etc.

 

[jmeckley]

if' you've only got 1 week, one end user, and limited documentation. I would get the end users POV for different modules.

depending on what you need either start with the 1. core functionality of the system, usually what makes it unique. or 2. What the end user doesn't like about the system. This will be a pain point when rewriting so if you document this in the beginning it may be easier to address later.

Depending on how "human readable" the code is, time may be better spent documenting from a developer's POV.

Jason Meckley
Programmer
Specialty Bakers, Inc.