Atom Atom feed

Document Templates Considered Harmful

Eric Burke strikes again with a document template for the creation of essays of the "X Considered 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:

line-chart.gif

_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