This post originated from an RSS feed registered with Java Buzz by Weiqi Gao. Original Post: Document Templates Considered Harmful Feed Title: Weiqi Gao's Weblog Feed URL: http://www.weiqigao.com/blog/rss.xml Feed Description: Sharing My Experience... Latest Java Buzz Posts Latest Java Buzz Posts by Weiqi Gao Latest Posts From Weiqi Gao's Weblog

Eric Burke strikes again with a document template for the creation of essays of the "X Xonsidered Harmful" genre.

This blog entry is an instantiation of that template. Here goes:

_Document templates___ Considered Harmful

Resolved: _Document templates_ _ is a poor choice for _documenting_the_design_of software systems______ and should be avoided at all costs.

With _30_________ years of experience in this field, I am an authority. I have seen countless examples of _document templates__________, all starting with good intentions but inevitably ending in failure.

You may think __document templates__ offers benefits, such as:

• _a unified format____________
• _a_sense_of_organized-ness_________

These seem OK on the surface, but consider the huge number of negative consequences:

• _It takes_a_huge_amont of time_to_learn_all_the templates_____
• _Nobody reads them, not even the original authors—they just fill them out____________
• _All of those ugly left-over underlined blank markers really distracts____________
• _____________
• _If you accidentally delete one of fields, it will take you a day to add it back____________
• _____________
• _____The underlines won't go away as you type and screw up all the formatting________
• _____________
• _____________
• The formatting gets ugly when you run out of the preformatted blanks

Now let’s look at an example:

_[link to] The SDLC template____________________________________________
_[link to] The ADR/DSOT templates (versions 1.2.3.4.5-1966 and 5.4.3.2.1-1987_ __ ____ ____________ ________ _________________
__ ______________________ _____________________

This works fine on _green field_projects________, but only when _the_team_is_small________. If you try _it on existing systems_with_thousands_of_developers_and_contractors_from dozens_of vendors_____, it will certainly fail with this result:

_No one can figure out what what the heck is going on_ ___________________________________________
_The ADT and the DDR_gets to be thousands of pages long and is of no help to anyone _______ ________ ________ ________ ________ ____

See the problem?

The data is compelling:

_Alex Miller____________ says it best on his blog in a comment in Eric's blog at __http: //stuffthathappens.com/blog/ 2007/06/07/__________- considered-harmful/#comment-9180 _______________ :

__Awesome. Now I can finally get around to doing that “Mad Libs Considered Harmful” blog I’ve been meaning to write for so long.
It also reminds me that I need to polish up my proposal to add GOTO to Java 7. ______________________
________________________

On your next project, think carefully before choosing _document templates___________. A quick Google search for the term _%$#@-ed up document templates ___________ seems to back this up — it returns over _____3_______ million matches!

References

• ___________ Considered Harmful __________ (someone’s blog)
• __Template (word processing)_________ (you need a wikipedia link)
• _Error 404 - Not Found__________ (more than one blog entry is helpful)