To read the article online, visit http://www.4GuysFromRolla.com/webtech/Documentation.shtml

Documenting ASP Applications


I recently received feedback from avid 4Guys reader Joseph R., who commented:

I would love to articles and or opinions on how to document an ASP/HTML application. Here at my office it is often complained about but never solved. Often peolpe just create a type of flow chart in vision showing the page to page links.

I couldn't agree more with Joseph, it would be nice to see articles on this topic. So, I sat down yesterday and decided to spend some time thinking about the topic. This led nowhere, unfortunately, since my experience with created large ASP applications in groups is fairly limited. For the few projects I worked on that involved groups of developers working on a massive ASP application, we used a pretty detailed technical specification document. At the time I was working as a consult for a company that always produced very thorough technical specs.

Due to my lack of experience in group ASP projects, I am not able to write a good article on the topic, so I'd like to try an open-source, community-involved article. This is the first time I've tried something like this, so it may crash and burn, but I'm hoping to get some good feedback, comments, and ideas from various 4Guys readers.

What I'd like to ask is for those who have experience working in large groups to send me information on what documentation methods were employed. Did you use any specific tools? How successful or useful was the documentation style you used? How do you think large ASP applications can be documentated best?

Even if you've not worked on a large ASP project in a group, but still have opinions on documenting, please share your thoughts as well. I am especially hoping some readers are familiar with documenting tools that work well with ASP applications.

I am excited to see if this community-based article takes off! Recently I read Nathaniel Borenstein's Programming as If People Mattered, in which the author explains the importance of anecdotes in computer education. I hope this effort obtains a number of good, educational anecdotes from ASP developers around the world. I hope to hear from you! :)

  • Share your opinions/views


    Selected Reader Feedback:
    I worked on a medium size ASP application within a large enterprise system (a document management system), and we had extensive functional and design specifications. Hundreds of pages of repetitive documents, hours of document review meetings. It was pretty...intense.

    I'm currently working pretty much solo on a large ASP application within another large enterprise system (a media rights management and fulfillment service), and I've got a todo list, an issues list, and a small amount of available whiteboard real-estate. I find this style of programming much more productive. Documents and meetings are evils of group software development.
    [Read More...]

    We comment our code the following way with a HTML comment tag at the top of the page, so it even can be seen by a view source in the browser. This way we know what tables, stored procedures, and session variables and request variables it uses. An administration running just an NT server with IIS can view the source of the page to see what it requires.
    [Read More...]

    No matter the size of the project, 99% of the screwups I have seen in the last year can be traced back to a poor requirements list.

    My company requires a "functional requirements list" (FRL) as part of the contract for any work. the FRL is generated while the project is in the systems analysis phase, when we sit down with the client to try to figure out what they want from us and what solution we are going to offer them. This is a list of every little thing the customer expects to find in the finished application. NO matter how obvious it is, if they want it, it goes into the FRL. If it is not in the FRL we will not honor it even if it is something really stupid, because every time you add one little thing to the project you lose money.
    [Read More...]

    I regularly deal with the problem of providing accurate documentation for our medium-to-large-sized web projects. I have gradually grown to embrace the philosophy to WRITE EVERYTHING DOWN. In the numerous projects I have produced, I find that the projects where documentation was a primary concern fared much better than non-documented projects. Besides, anyone who has taken any programming classes knows that the best programmers spend about as much time writing out the project as they do doing the actual coding. This has benefitted us as a company in several ways.
    [Read More...]

    Regarding Documenting: I've worked on a variety of both small and medium-sized ASP applications, both solo and as part of a group. Whether I'm working alone or not, I always find it best to resort to the old method of documenting via a flowchart. I picked up this method during college, in the early eighties. Flowcharting works well for not only the mainframe and PC languages I was taught then, (and all of the applications I've worked on since then) but also for HTML/ASP applications.
    [Read More...]

    Incremental is the way. Dynamic is the way. Especially in these crazy times. I've spent the last year coding on the fly. I'm a smart guy. I know what I'm doing. If I die, my code is amazingly annotated. If I'd spent the last year designing the system I'm working on (which I could have, believe me), a) my competition would already have been "first mover" and I'd need to think of something new to do, and b) the technical world and consumer market would have shifted radically. And given the number of paradigm shifts my boss has dropped on me in the last year, I have no regrets about lack of prior planning.
    [Read More...]


  • Article Information
    Article Title: Documenting ASP Applications
    Article Author: Scott Mitchell
    Article URL: http://www.4GuysFromRolla.com/webtech/Documentation.shtml


    Copyright 2017 QuinStreet Inc. All Rights Reserved.
    Legal Notices, Licensing, Permissions, Privacy Policy.
    Advertise | Newsletters | E-mail Offers