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! :)
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
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.|
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.
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.
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.
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.