×
INTELLIGENT WORK FORUMS
FOR COMPUTER PROFESSIONALS

Log In

Come Join Us!

Are you a
Computer / IT professional?
Join Tek-Tips Forums!
  • Talk With Other Members
  • Be Notified Of Responses
    To Your Posts
  • Keyword Search
  • One-Click Access To Your
    Favorite Forums
  • Automated Signatures
    On Your Posts
  • Best Of All, It's Free!
  • Students Click Here

*Tek-Tips's functionality depends on members receiving e-mail. By joining you are opting in to receive e-mail.

Posting Guidelines

Promoting, selling, recruiting, coursework and thesis posting is forbidden.

Students Click Here

Jobs

How to document an existing system?

How to document an existing system?

How to document an existing system?

(OP)
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!
 

RE: How to document an existing system?

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.

RE: How to document an existing system?

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

"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::PerlDesignPatterns)

RE: How to document an existing system?

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)

RE: How to document an existing system?

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?

RE: How to document an existing system?

(OP)
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. big smile

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.

RE: How to document an existing system?

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.

Red Flag This Post

Please let us know here why this post is inappropriate. Reasons such as off-topic, duplicates, flames, illegal, vulgar, or students posting their homework.

Red Flag Submitted

Thank you for helping keep Tek-Tips Forums free from inappropriate posts.
The Tek-Tips staff will check this out and take appropriate action.

Reply To This Thread

Posting in the Tek-Tips forums is a member-only feature.

Click Here to join Tek-Tips and talk with other members! Already a Member? Login

Close Box

Join Tek-Tips® Today!

Join your peers on the Internet's largest technical computer professional community.
It's easy to join and it's free.

Here's Why Members Love Tek-Tips Forums:

Register now while it's still free!

Already a member? Close this window and log in.

Join Us             Close