Code your Documents · Brian Hartsock's Blog

Every developer has heard the phrase document your code. The reason this is important is the functionality is now coupled with a description of how it works. Now a future developer can load up a single source of information and understand the functionality. But, more importantly, the odds of the documentation staying updated are higher because of this coupling. The same can’t be said for a standalone document.

Well, shouldn’t the same be true for documents, specifically those that describe some sort of process? For example, a document describing the steps to setup an IIS web server for a particular application is perfect to convert to an automated script. So, today, I started on a simple script to setup IIS compression using MSBuild.aspx).

<project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">


  <propertygroup>
    <adsutilpath>C:\inetpub\AdminScripts\adsutil.vbs</adsutilpath>
    <cscriptpath>cscript</cscriptpath>
    <staticfilestocompress>html htm js txt</staticfilestocompress>
    <dynamicfilestocompress>aspx asp dll exe axd</dynamicfilestocompress>
  </propertygroup>

  <target name="IisCompression">

    <message importance="high" text="Turn on static and dynamic compression for all of IIS."></message>

    <exec command="$(cscriptPath) $(adsutilPath) set w3svc/filters/compression/parameters/HcDoStaticCompression true"></exec>
    <exec command="$(cscriptPath) $(adsutilPath) set w3svc/filters/compression/parameters/HcDoDynamicCompression true "></exec>

    <message importance="high" text="Select files to compress for static and dyanamic compression."></message>

    <exec command="$(cscriptPath) $(adsutilPath) set W3SVC/Filters/Compression/Deflate/HcFileExtensions $(StaticFilesToCompress)"></exec>
    <exec command="$(cscriptPath) $(adsutilPath) set W3SVC/Filters/Compression/gzip/HcFileExtensions $(StaticFilesToCompress)"></exec>
    <exec command="$(cscriptPath) $(adsutilPath) set W3SVC/Filters/Compression/Deflate/HcScriptFileExtensions $(DynamicFilesToCompress)"></exec>
    <exec command="$(cscriptPath) $(adsutilPath) set W3SVC/Filters/Compression/gzip/HcScriptFileExtensions $(DynamicFilesToCompress)"></exec>

  </target>
</project>

Not only does this script automate the process, but it serves as a living document for the process. By doing this, the documented process is now coupled to the task itself.

The next step to coding processes is coding tasks that can’t be automated. For example, during a deployment, if some sort of fatal error occurs, the next task might be to call your boss and clean up your resume. Why not code a message in the deploy script to give you the list of people and phone numbers to call in case of an emergency, then load up your resume in Word? Again, the documented process is now coupled with the task itself.

Obviously, this article grows out of my dislike of documentation. I dislike it, not because it isn’t useful, but because it takes a lot of time and, in my personal experience, isn’t used very often. By integrating the documentation with the task itself, I think we gain more value from it.

Menu