Howto ducument your app 3

[aspnetvbnetnerd]

I can't find a forum where I should post.

I have to document my application that is written in VB.NET, C#.
Is there anyone that has any good experience with this or any link that I can read on or something else.

George

 

[Glenn9999]

First question: Is this user or system documentation you are writing?

The requirements are much different for each one.

 

[aspnetvbnetnerd]

No, I am writing it for other developers.

What I have thought is with visio create the logic with Infaces and classes.

But then I have nothing.

 

[Glenn9999]

alright, you're looking for system documentation, then. I'll see what I can remember from my days of writing it and might add more if I miss anything major. But the basic idea:

1) You're not looking to document the obvious - so you don't want to get too specific. You don't want anything too language specific either. Basically you are NOT necessarily documenting the logic of each program - if I can get the idea of something from looking at the program, then it's not worth documenting. You're looking to document the not-so-obvious in a way that any programmer will understand the system.

Example items to definitely document:
2) Data flows: How does data enter and exit the system? Does it come in from a file, terminal, etc? What path does it take to an exit (printer, file, offsite processor)? Which programs touch the data and in what ways do they touch it (input, processing, reporting?)?

3) Data descriptions: What does each field represent, in terms that are language neutral? In other words, what does the data field mean and how do I access it (again language neutral)? If it has some kind of code numbering, define all the codes and what they represent.

4) Workflow processing: Again in language neutral terms, what am I doing to the data at each step? What is the process involved in reporting the data at each step? This is as close to direct program documentation you will get in most cases, but again we want the non-obvious, not what can easily be figured out. Program 1 does A, B & C; Program 2 does E, F, and G, etc.

5) Program dependencies: What programs get called by other programs (DLLs, widely used in-house OBJects & LIBraries, standard utilities)? What data files are required at each step? What other resources are required for the program to work correctly (DB up and running, DB IDs, certain user ids, certain permissions, web server in the case of web apps, runtimes in the case of interpreted languages)?
This basically your system trouble-shooting section - your external requirements so the programs run properly.

6) Detail documentation: This is where you would document the specific program processes that would NOT be clear upon inspection of the program. You would not document specifically each step, but the things that are overly complex in logic (example: I did a couple of data-driven logic programs which required thorough documentation of logic because the function was not obvious to others) or requirements (example: edit checks on data). This should be very minimal in most cases.

Hope this helps you some.

 

[aspnetvbnetnerd]

Thanks.

George

 

[philhege]

And take a look at Sandcastle for class/function documentation. I've had decent success with it.

> MS has an initiative that looks promissing:

>

http://www.sandcastledocs.com/Wiki Pages/Home.aspx

I vote for Sandcastle too. And of course the necessary companion:

http://www.codeplex.com/Wiki/View.aspx?ProjectName=SHFB

Phil Hegedusich
Senior Programmer/Analyst
IIMAK

http://www.iimak.com

-----------
A virtual machine ate my accounting data. I transferred it to a physical box, then I beat it to smithereens with a sledgehammer. I feel better.

 

[chrissie1]

you're not making sense fill. Iy(s like you'r talkint to yourself ;-).

Christiaan Baes
Belgium

My Blog

 

[rjoubert]

If you are writing this documentation for other developers, I would also suggest putting some descriptive comments in your source code. Put a descriptive block at the beginning of each code module with a brief rundown of the purpose of the code module, a block at the beginning of each procedure/function to explain the purpose of the procedure/function, and then sprinkle in some one or tow liners to explain certain blocks of code or lines of code that may not be obvious.

 

[philhege]

you're not making sense fill. Iy(s like you'r talkint to yourself

A judicious use of the quote tag would have helped.

But, yes, I do talk to myself. And sometimes I answer back.

 

[chrissie1]

Who's "judicious"? ;-)


Christiaan Baes
Belgium

My Blog

 

[AlexCuse]

I'm a big fan of CodeDoc (for C#).

http://www.dwell.net/CodeDoc/

Its' really simple to use, and its' output is a nice reward for commenting your code

[small]----signature below----[/small]
I'm pushing an elephant up the stairs

My Crummy Web Page

 

[aspnetvbnetnerd]

I think code of the application is well doucmented

AlexCause does CodeDoc works for vb.net?

 

[AlexCuse]

I don't believe it does, I think that the website would say for sure.

You say the code is well documented. Is it done using the XML Comments (I think these were not added to VB.net until 2005?)


[small]----signature below----[/small]
I'm pushing an elephant up the stairs

My Crummy Web Page