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

ASP Project Documentation Anecdotes


The following are some anecdotes on large ASP project documentation projects shared by various 4Guys visitors.


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.

As for good group programming, I think it's best to get all team members on the same page mentally rather than via documentation. If you can all see the big picture, or at least a few good oracles/visionaries can see it, you're better off than with any amount of UML/Visio/Inspiration/Word/Notepad work. I find documentation a waste, especially if some illusion of maintainable accuracy is perceived. People's conceptions are much more malleable and forgiving and adaptive than documents. The holy grail of documentation and design is to be able to map every user and functional requirement to every line of code. This may some day be attainable for a fixed system (yeah, right!), but introduce any amount of change and you'll have too much document thrash. Real live human beings will always be the best way answer questions like "How does this system work?" or "What systems will be affected by this change?"

I think if you can get your team in a room with a whiteboard for a couple hours and lay down how it is and how it should be, and then make individuals responsible for their own areas, and have everybody document their code like crazy, and design in a consistent and modular way, and use debug/validity tools like assertions and automated test suites to keep everybody honest, you'll be many wasted print outs and meeting hours ahead of your competition.

That said, I find user manuals to be great forms of documentation. They are necessary evils even for web sites (what's a FAQ but a shy user guide?), and they make for better reading than technical documents since they are at the user level. You can hire technical writers (non-techies) to write them, and that process alone will turn up plenty of functional lackings and ambiguities.

HTML/ASP work has the potential of being self-documenting since you can add tooltip support and blurbs of helpful text very easily throughout a system, and since the coders are responsible for writing this, it tends to make for clearer UIs, since if it has to be described and it's hard to describe, it ought to be simplified.

Restrict internal and external complexity to that which is necessary: users like simple UIs, other coders like simple interfaces and easy-to-follow code. You know you've reach KISS zen when you feel no shame or confusion describing your UIs and code.

To summarize, don't do technical documents. Get at least a few engineers up to full speed so they can draw good diagrams on whiteboards as needed, but don't worry about preserving this sort of work digitally or otherwise. These engineers are your precious asset, not documents or documentation tools. Make use of technical writers to describe your system at the user level, and/or make your application self-documenting. Keep it simple, and you won't hardly need to document at all.

Michael B.


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. Here is the page:

<!--
Status:			BETA
Database(s):	cms_sql.cmsopen
Page:			firm_docket.asp
Description:	Displays Docket Information	for Docket Calendar
Query String:	date	   - Date month falls on or day for daily view.
				id		   - User ID
				wkgp	   - Pracitce Area Workgroup, but
				             session variable is used
				             instead now.
				client	   - Client Number
				matter	   - Matter Number
				type	   - I for Individual User, G for 
				             Group/Practice Area, 
				             C for Client Matter
				view	   - M for Month, D for Daily, 
				             blank defaults to Daily
				activity   - Activity code to filter by
Session Variab:	gs_UserID,gs_WorkGroupCode,gs_WorkGroupDesc
Stored Procs:
Tables:			pmm_event
				pma_calndr_notf
				hbm_client
				hbm_matter
				hbl_work_group
				hba_persnl_wkgp
				hbm_persnl
				pml_priority
				pml_actvty_typ
				_tbl_court_name
				pais_actvty_cde_exc
				pmm_text
Includes:		/pais/include/ASPCommon.inc
				/scripts/includes/ADOVBS.inc
				/pais/include/toolbar.inc
				/pais/include/footer.inc
Created:		February 7, 2000
Created By:		Norman King
Last Updated:	04/07/2000
Last Upd By:	Norman King
Last Upd Reason:Updated session variables and added 
                session timeout handler.
-->

When I work on a large ASP application, I tend to document as I go along. After I Dim every variable I use, I add a comment after it to explain what it is used for. This is helpful in case I forgot what it was used for, or if someone else on the team I am on wants to modify the program.

Using a naming convention also helps. Start up names with "i" if an Integer, "s" if a string, "b" if a Boolean, "r" if a real, "v" if a variant, "d" if a date, etc. Also I put in addition to those, an "a" in front if it if an array, or "g" if it is a global variable. Then I add in an underscore and the name of the variable. So gs_UserID would be the global string I store the user's ID in. With this form of documentation, it makes reading the code a lot easier.

I also add whatever thoughts I have on the code to the comments before the code. Like:

' This code will check to see if the Date is Y2K compliant

or

' Parse out the event query by reading in the date
' submitted by the user in Request.Form("start_date")

Little things like that help to make the code more readable, and better documented.

I don't use any tools to document the code. It is all done by me.

Norman K.


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.

Once the FRL is ready, it is broken down in chunks that can be managed by an individual programmer. One or two programmers and the html designer or graphics artist put together the global headers and footers for the formating of the files, and skeleton files for the main sections. These files are put together in a development web server and the whole thing is added to a version control system like PVCS or Visual Source Safe.

On most cases each module represents an item in the FRL. Module "security" will span whatever number of ASP/html pages are needed to secure the site, login users, etc. When the project manager tracks down tasks it is done by module, and usually one programmer is responsible for it and all its files.

I follow this method even when working on smaller scale projects or stuff on my own because it keeps it orderly. It is very easy to track progress when you know how many functions out of the total are completed.

The other thing that keeps it tidy is to documment the heck out of your code. One of the laws of programming is that whatever code you write now will not make sense to you after a few weeks. A few comments here and there will make your life easier later.

Pedro


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.

I would also suggest the following book:

  • Collaborative Web Development: Strategies and Best Practices for Web Teams
    by Jessica Burdman - ISBN:0201433311

    It is not ASP specific, but it is web oriented and technology oriented. I would highly recommend the book for anyone desiring to document and manage a large-scale project.

    I will be watching (and participating) in interest this topic of documentation.

    Don M.


    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.

    The flowchart should show an overall viewpoint of the application, specifically focusing on the possible paths (and pages) a user can take. Detail regarding a page can be written to the side of whichever page requires the explanation. Each page (including error message pages) should be shown on the flowchart.

    The information from the flowchart is typically taken from business analysis documents (requirements) that are written in conjuction with the end users of the requested functionality prior to the actual start of coding. Depending upon the complexity of the project (as well as the knowledge level of the other programmers involved) these requirements may be translated into programming specifications.

    I've found that by using a combination of the flowchart, the requirement document, the specification, and the source code comments created by the programmers, it is rather easy to provide documentation for a system once it has been completed. During the development cycle, the flowchart, requirements, and specifications generally provide all of the documentation necessary.

    Dave


    What fun! It looks like the XP vs. waterfall battle rages on. I think you got the full spectrum, from the lone wolf XP crew (me) to the classic requirements driven guys (Pedro).

    To continue the battle, I submit that I have not worked on a single real software application that was successfully defined up front. Rather, I've seen apps and companies start at point A, and end up Z'. This phenomenon seems to be independent of documentation.

    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.

    To be fair, my functional requirements have heretofor been generated internally, and will always be decided on internally (sorry users, it's not a democracy after all). If an outsider were calling the shots, I might be more formal.

    Amen to well documented ASP. I really like the header style Norman K. presented. I want to run around to all the pages and do something like that on my project. The notion of self-documenting systems is good, and I agree that a lack of documentation tools is a good thing. My boss got me hooked on Notepad, and I haven't cracked Word or Inspiration since.

    Michael B.



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


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