Standards Doc App

Use Case: Engineering Standards Document Repository

I was approached by our department's senior software architect to assist in refactoring their development standards documentation process.

The Engineering Standards team was responsible for creating, documenting, and monitoring development standards and their use across the organization. Each standard was developed by one or more people. Each draft standard would be reviewed by multiple people, then accepted and published. Over time, some standards were deprecated; however, all documentation was archived for historical purposes.

When the project reached me, there were approximately 50 standards documents in various stages. The current index of standards was a hand-edited tabular list which no longer matched the actual documentation. There was no standard for creating standards documentation.


  • Documents created by copying and modifying an existing document
  • No standardized "look" to pages
  • New pages manually added to an index table
    • Recently accepted documents manually marked as "New" NEW
      (with risk of forgetting to remove NEW over time)
      allowing for the possibility of NEW deprecated entries
    • Lack of standardization makes some table columns "brittle"
  • Not easy to search (e.g. "Show me only Mandatory Standards")
  • Lots of manual effort


  • Documents started using a form to capture required metadata
  • Template provides standardized "look" to pages
  • New pages dynamically indexed
    • Recently accepted documents marked as "New" NEW based on date comparison
  • Easy to search (e.g. "Show me only Mandatory Standards")
  • Manual effort confined to writing the differentiated content

Feature: Creation of new documents


  1. Open an existing document
  2. Select and copy the content, taking care not to change anything
  3. Start a new document, pasting in copied content
  4. Edit out what doesn't fit the new standard
  5. Edit in new content
  6. Try to include all required sections...?
  7. Review and compare to other documents.
  8. Edit, repeating steps 4-7.


  1. Enter required meta data in a form.
  2. Add document-specific content to the resulting template.

See StandardsDocCreate.

Feature: Index table of all documents.


Table is updated by hand. Are entries in sorted order?

See StandardsDocIndexBefore.

(only 2 entries shown!)

%EDITTABLE{format="|textarea, 2x30|select, 1, Mandatory, Standard, Aspiring, Recommended Practice, Intriguing Practice, Deprecated|date, 11, Jan/2010, %d/%b/%Y|select, 1, Development Process, Platform, Serving, Globalization, Deployment, Networking, Batch Processing|label|label|" changerows="add" }%
| *Name* | *Status* | *Date of Adoption* | *Area* | *PM Contact* | *Engineering Contact* | *Applies if...* | *To comply* |
| [[StdTracking][Defect Tracking: Bugzilla (bug.corp)]] | Mandatory | 01/Jun/2006 | Development Process | %SEARCH{"PM Contact" topic="StdTracking" regex="on" nonoise="on" format="$pattern(.*?PM\sContact\:\*\s*([^\n\r]+).*)"}% | %SEARCH{"Engineering Contact" topic="StdTracking" regex="on" nonoise="on" format="$pattern(.*?Engineering\sContact\:\*\s*([^\n\r]+).*)"}% | Always | Must use Bugzilla to track bugs |
| [[StdPkg][Packaging/Repository: yinst (dist)]] | Mandatory | 01/Jun/2006 | Development Process | %SEARCH{"PM Contact" topic="StdPkg" regex="on" nonoise="on" format="$pattern(.*?PM\sContact\:\*\s*([^\n\r]+).*)"}% | %SEARCH{"Engineering Contact" topic="StdPkg" regex="on" nonoise="on" format="$pattern(.*?Engineering\sContact\:\*\s*([^\n\r]+).*)"}% | Publishing or deploying  software | Must use packaging format and dist repository |


Table is built dynamically. Entries are always sorted.

See StandardsDocIndex.

| *Name* | *Compliance Level* | *Status* | *Date of Adoption* | *Area* | *PM Contact* | *Engineering Contact* | *Applies if...* | *To comply* | *Created On* | *Created By* | 
format="| [[$topic][$formfield(StandardName)]] %IsNew% %IsDep% | %FieldsToShow% | $createdate | $createwikiusername |"

Feature: Documents marked as "New" or "Deprecated*.


"New" and "Deprecated" added manually to each row. ("New" must be removed manually, as well.)

| [[StdScm][%N% Source Control: Subversion]] | Mandatory | 01/Mar/2009 | Development Process | ... |

| [[StdBuild][%N%<del>Automated Build</del>]] | Deprecated | 01/Jun/2006 | Development Process |...

What does it mean to be new (%N%) and also deprecated (<del>)?


"New" and "Deprecated" are calculated for each row, based on date comparison or metadata values. Set up variables once and let the computer do the rest. A different icon signifies "Deprecated".

   * Set IsNew = $percntCALC{$IF($formfield(DateAccepted), $IF( $TIME($formfield(DateAccepted)) > $TIMEADD($TIME(), -6, month), $percntN$percnt, ), ) }$percnt
   * Set IsDep = $percntCALC{$IF($EXACT( $formfield(Status), Deprecated ), $percntX$percnt, ) }$percnt

Feature: Format of each document


No standardized look and feel. Copy and paste.

  • Sample document before templatizing:


Standardized Look and Feel automatically applied using templates.

See StandardsDocForm, %FORMFIELD{"StandardName"}% (%TOPIC%), StandardsDocTemplateFormat.

  • templatized document (screenshot):


Same search options as for any page.



Specialized search concentrates on metadata.

See StandardsDocIndex.


The App

This topic: Apps > WebHome > StandardsDocApp
Topic revision: 16 Dec 2014, VickiBrown
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email