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.

Before

  • 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

After

  • 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

Before

  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.

After

  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.

Before

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 |
...

After

Table is built dynamically. Entries are always sorted.

See StandardsDocIndex.

%TABLE{sort="on"}%
| *Name* | *Compliance Level* | *Status* | *Date of Adoption* | *Area* | *PM Contact* | *Engineering Contact* | *Applies if...* | *To comply* | *Created On* | *Created By* | 
%SEARCH{
search="META:FORM{name=\"StandardsDocForm\";META:FIELD{name=\"Status\".*?value=\"%URLPARAM{"qStat"}%;META:FIELD{name=\"Compliance.*?value=\"%URLPARAM{"qCompl"}%;META:FIELD{name=\"Area\".*?value=\"%URLPARAM{"qArea"}%;"  
%SearchParams%
format="| [[$topic][$formfield(StandardName)]] %IsNew% %IsDep% | %FieldsToShow% | $createdate | $createwikiusername |"
}%

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

Before

"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>)?

After

"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

Before

No standardized look and feel. Copy and paste.

  • Sample document before templatizing:
    SampleStandard_Orig.png

After

Standardized Look and Feel automatically applied using templates.

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

  • templatized document (screenshot):
    SampleStandard_Template.png

Before

Same search options as for any page.

Search_before.png

After

Specialized search concentrates on metadata.

See StandardsDocIndex.

Search_after.png

The App

Topic revision: r8 - 16 Dec 2014, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback