Fog Creek Software
Discussion Board




Documenting ASP/HTML Applications

Having spent several weeks perusing an endless array of information on a) the web, b) newsgroups, c) local geek-tech bookstore, d) disucussion forums, and e) local and online user groups, I've discovered several things:

1.  Basic HTML/JScript/ASP applications are at nearly every shop out there, in one form or another (please replace ASP with PHP, JSP, etc. if necessary).

2.  Nearly every developer (still speaking ASP/HTML here) has either inherited code with sub-standard documentation (if any at all), been involved in a web project with no thought to documentation from the outset of the project, or has considered code with decent JScript, ASP, HTML comments to be "documentation".

3.  Nearly every developer (but not all) blames the prior development team for poorly developed applications prior to their own arrival on a project.

With that said, I jump into the fray....

Having recently entered a new position, I find myself in a situation where I would like (need) to produce a "manual" of sorts for my web applications, intended primarily for a technical audience.  This site is comprised of over 50 completely independent applications, each with a very specific function (P.O. System, Contacts, Service Request Mgmt., etc.).  Some of these pieces are aware of one another, others are not.

For example:  One application consists of a couple hundred ASP files, each of which calls linked .js files, .css formatting files, as well as separate includes for data access, data rendering, etc.

How in the world can I render this in a "tech manual" format?  I've found only one article on using a bastardized UML-type strategy, but it fell a bit short, as I've got no objects that are called (ex-developer liked Functions & Subs) and I'm dealing with a bunch of scripting (non-OO) languages.

I've found quite a few source-code analysis tools and parsers for objects of all languages, but it seems that I'm the only ASP guy out there who's interested in a complete (and documented solution).  ASP/JScript/HTML parsers are few and far between, I'm afraid.

I humbly bow to those of you who have found a solution to this scenario and are willing to share.

Jeff MacDonald
Monday, May 06, 2002

You are totally screwed. ASP/JSP/PHP/Web applications are the COBOL disasters of this millenium. Completely un-documentable. I'd try to avoid this task if possible.

On the other hand, if you are a sadist and develop some way to automate this, you would be considered a god in IT. Just remember being a god in IT is sort of like being the governor of North Dakota...

good luck
Monday, May 06, 2002

Crap. It's easy to document a JSP application if it is designed well-- minimal use of scriptlets (taglibs instead), and a strong MVC framework.

It's also possible to document an ASP, PHP, or JSP application if it's designed carefully and consistently.  As long as you can outline the data structures and basic application flow, you should be fine. It won't be the most rigorous documentation out there, but it will be a lot better than nothing.

If your code is a mess, well, then it'll be difficult to document. This is true whether or not it's a web application.

Matt Christensen
Monday, May 06, 2002

While not 100% what you're looking for, I found this tool to generate far more documentation from my ASP/T-SQL/COM projects than I would have dared imagine. The .Net version will be out soon, as well.

http://www.livingaddress.com/livdoc/eng/livingdoc.asp

Ryan LaNeve
Monday, May 06, 2002

I agree that documenting template+script (ASP, PHP, JSP etc.) applications is especially difficult.  I see two reasons, each one a major obstacle in its own right and together a killer:

1. You have very different kinds of code, declarative (HTML) and procedural (the scripting language), generally crafted by different people, intricately mixed together.

2. The organizing principle of ASP/HTML and its ilk is, at the top level, the same as for plain HTML: weak and flat.  Weak because it is file-system-based (a page is a file) and therefore untyped; flat because there is no abstraction hierarchy, therefore no natural separation of general and specific functionality.

The above factors don't just make documentation harder, they make development and maintenance harder too.

I recently came up with a way to eliminate these two obstacles.  It's far from done but far enough along that the advantages are already evident.  The idea is simple: an object-oriented markup language that can do the work of both the HTML and the scripting language.  You can see what I've come up with so far at http://www.bentodev.org

Michael St. Hippolyte
Monday, May 06, 2002

Well, I appreciate the input.  Sometimes, being screwed is okay as long as everyone else agrees you're screwed.  I was quite amazed that I could find so few tools out there...At least now I know I'm not alone/insane.

Thanks for the pointers to these tools - I'm sure they'll come in handy.

Jeff MacDonald
Tuesday, May 07, 2002

*  Recent Topics

*  Fog Creek Home