edocs-development Mailing List for edocs

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Here's my proposal for structuring the design documentation.

As a foundation to base this proposed format on, I've loosely
followed the format and structuring of a Design Pattern (from
the Gang of Four book).  Unlike a design pattern, there is no
intention to be general, but rather specific (in particular,
progressively less general and more specific the deeper
a design goes).

Right now, Use Case documents are named U##.xml or A##.xml.

My recommendation is that Design documents ("programming
specifications") should be prefixed with PRG (for "PRoGramming").
As the extension will remain .xml, and not .cpp, .bas, or .java,
these are still documentation and not implementation source files.

Following the PRG prefix is a #### number.  To allow for several
hierarchical levels of abstraction (a high-level design, a low-level
design of multiple classes, and a detailed-level design of the
intricacies of a single class), we should allocate thousands to
functional aspects of eDocs' behavior.

For instance,

1000 Search Engine
: :
9000 eDocs-Microsoft Integration

A high-level Microsoft Integration Design document (perhaps describing the
overall web services architecture by which Microsoft Integration takes
place, relying on lower-level Design documentation to focus in on narrow
areas) would be named PRG9000.XML

To take this another level deeper, we may create the following Design documents
covering the design of the Web Services interoperability:

PRG9000.XML   Web Services Integration : Architectural Overview
    PRG9010.XML  Design of the WSDL Interface
    PRG9020.XML  User Authentication : HTTP Cookie? SOAP Header Extension?  Session ID argument with each SOAP Call?
    PRG9030.XML  User Authorization : XML Representation of eDocs Roles and Privileges
    PRG9040.XML  Encoding : File Transfer via BASE64 encoding ; encryption?
    :   :
    PRG9100.XML  eDocs-Microsoft Integration : Architectural Overview.
        PRG9110.XML Microsoft SOAP Toolkit 2 : Specific configuration and technical issues
        PRG9120.XML Apache SOAP 2.3 : Specific configuration and technical issues
    PRG9200.XML  Client-side COM Component : IDL interface, ATL responsibilities, deployment
        PRG9210.XML C++ Design of IEDocsCredentials Implementation
        PRG9220.XML C++ Design of IEDocsNavigator Implementation
        PRG9230.XML C++ Design of IEDocsLocalRepository Implementation
        PRG9240.XML C++ Design of ISupportErrorInfo Implementation for extended error information
         :  :
    PRG9300.XML  Microsoft Word Integration : Add-in Model and Considerations for using SOAPClient from VBA
        PRG9310.XML Design of the Log-In Form : user interface and interactivity
        PRG9320.XML Design of the Check-In Dialog : user interface and interactivity
         :  :
    PRG9900.XML  Microsoft Windows Explorer Integration
        PRG9910.XML Design of a Namespace Extension
        PRG9920.XML Design of Explorer User Interface

There's nothing that inherently prohibits cross-references between design
documents.  For example, it's entirely possible PRG9400.XML may describe
Excel Integration (so that Excel spreadsheets can be managed by eDocs),
and instead of duplicating the content of PRG9310.XML, PRG9320.XML, etc.,
it will simply refer to these design documents (provided design content
is largely equivalent between Word and Excel contexts, the design is
reusable).

For the template of the XML, currently I'm working with something like the
following (you can ignore the {$*} tags, they're just for a generator I'll use
to export design specs):

- - - ProgSpecTemplate.xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- Copyright notice and GPL statement go here -->
<document url="./{$ID_LOWERCASE}.xml">
 <properties>
  {$BEGIN_LOOP}
  <author>{$AUTHOR}</author>
  {$END_LOOP}
  <title>{$ID_UPPERCASE}. {$TITLE}</title>
  <previous name="{$PREVIOUS_SECTION} Index" href="../{$PREVIOUS_SECTION_LOWERCASE}_index.html" />
 </properties>
 <body xml:lang="en-US" >
  <section name="Brief Description" href="toc">
   {$BRIEF_DESCRIPTION_HTML}
  </section>
  <section name="Detailed view" href="toc">
   <detview-section name="Characteristic Information" >
    <detview-section-item name="Goal">{$INTENT_PURPOSE_HTML}</detview-section-item>
    <detview-section-item name="Scope">{$SCOPE_HTML}</detview-section-item>
    <detview-section-item name="Rationale">{$INTENT_RATIONALE_HTML}</detview-section-item>
    <detview-section-item name="Consequences">
     {$CONSEQUENCES_RESULTS_HTML}
     {$CONSEQUENCES_TRADEOFFS_HTML}
    </detview-section-item>
    <detview-section-item name="Related Use Cases">
     <ul>
     {$BEGIN_LOOP}
      <li><a href="{$RELATED_USE_CASE_ID}.html">{$RELATED_USE_CASE_ID}.</a> {$RELATED_USE_CASE_TITLE}.</li>
     {$END_LOOP}
     </ul>
    </detview-section-item>
    <detview-section-item name="Future Extensions">
     <table>
     {$BEGIN_LOOP}
     <tr>
      <td>{$LIKELY_FUTURE_EXTENSION_HTML}</td>
      <td width="10%">{$LIKELY_FUTURE_EXTENSION_SCOPE}</td>
      <td width="10%">{$LIKELY_FUTURE_EXTENSION_LIKELIHOOD}%</td>
     </tr>
     {$END_LOOP}
     </table>
    </detview-section-item>
    <detview-section-item name="SAAM Score">{$SAAM_SCORE}</detview-section-item>
   </detview-section>
   <detview-section name="Structure">
    <detview-section-item name="Architecture">{$ARCHITECTURE_HTML}</detview-section-item>
    <detview-section-item name="Data Dictionary">
     <table>
      <th>
       <td>TERM</td>
       <td>TYPE</td>
       <td>WIDTH</td>
       <td>NULL?</td>
      </th>
      {$BEGIN_LOOP}
      <tr>
       <td class="ddterm">{$DATA_DICTIONARY_TERM}</td>
       <td class="ddtype">{$DATA_DICTIONARY_DATATYPE}</td>
       <td class="ddlen">{$DATA_DICTIONARY_WIDTH}</td>
       <td class="ddnil">{$DATA_DICTIONARY_NULLABLE}</td>
      </tr>
      <tr>
       <td class="dddef" colspan="4">{$DATA_DICTIONARY_DEFINITION}</td>
      </tr>
      {$END_LOOP}
     </table>
    </detview-section-item>
    <detview-section-item name="CRC">
     <table>
      <th>
       <td>CLASS</td>
       <td>RESPONSIBILITIES</td>
       <td>COLLABORATORS</td>
      </th>
      <tr>
      {$BEGIN_LOOP}
       <td><b>{$CLASS_NAME}</b></td>
       <td>{$CLASS_RESPONSIBILITIES_HTML}</td>
       <td>{$CLASS_COLLABORATORS_HTML}</td>
      {$END_LOOP}
      </tr>
     </table>
    </detview-section-item>
   </detview-section>
   <detview-section name="Implementation">
    <detview-section-item name="Techniques">{$IMPLEMENTATION_TECHNIQUES_HTML}</detview-section-item>
    <detview-section-item name="Pitfalls">{$IMPLEMENTATION_PITFALLS_HTML}</detview-section-item>
    <detview-section-item name="Technology-specific Issues">
     <ol type="number">
      {$BEGIN_LOOP}
      <li>
       <h3 class="imphdr_q">{$IMPLEMENTATION_TECHNOLOGY_ISSUE_QUESTION}</h3>
       {$IMPLEMENTATION_TECHNOLOGY_ISSUE_ANSWER_HTML}
      </li>
      {$END_LOOP}
     </ol>
    </detview-section-item>
    <detview-section-item name="Platform-specific Issues">
     <ol type="number">
      {$BEGIN_LOOP}
      <li>
       <h3 class="imphdr_q">{$IMPLEMENTATION_PLATFORM_ISSUE_QUESTION}</h3>
       {$IMPLEMENTATION_PLATFORM_ISSUE_ANSWER_HTML}
      </li>
      {$END_LOOP}
     </ol>
    </detview-section-item>
    <detview-section-item name="Language-specific Issues">
     <ol type="number">
      {$BEGIN_LOOP}
      <li>
       <h3 class="imphdr_q">{$IMPLEMENTATION_LANGUAGE_ISSUE_QUESTION}</h3>
       {$IMPLEMENTATION_LANGUAGE_ISSUE_ANSWER_HTML}
      </li>
      {$END_LOOP}
     </ol>
    </detview-section-item>
   </detview-section>
  </section>
  <section name="Related Information" href="toc">
   <detview-section name="Sample Code (fragments)">
    {$BEGIN_LOOP}
     <a name="SAMPLE_{$ID_UPPERCASE}_{$IDX}">
     <sampleCode
      relPath="{$SAMPLE_CODE_RELPATH_SPEC}"
      static="{$SAMPLE_CODE_STATIC}"
      start="{$SAMPLE_CODE_START_LINE_NUM}"
      end="{$SAMPLE_CODE_END_LINE_NUM}"
      alt="{$SAMPLE_CODE_CAPTION}" />
     </a>
    {$END_LOOP}
   </detview-section>
   <detview-section name="Class Diagrams">
    {$BEGIN_LOOP}
    <a name="CLASS_{$ID_UPPERCASE}_{$IDX}"><img src="./diags/class/{$ID_UPPERCASE}_c{$IDX}.png" alt="Class Diagram {$IDX}." /></a>
    {$END_LOOP}
   </detview-section>
   <detview-section name="Sequence Diagrams">
    {$BEGIN_LOOP}
    <a name="SEQ_{$ID_UPPERCASE}_{$IDX}"><img src="./diags/seq/{$ID_UPPERCASE}_i{$IDX}.png" alt="Sequence Diagram {$IDX}." /></a>
    {$END_LOOP}
   </detview-section>
   <detview-section name="Statechart Diagrams">
    {$BEGIN_LOOP}
    <a name="STD_{$ID_UPPERCASE}_{$IDX}"><img src="./diags/std/{$ID_UPPERCASE}_s{$IDX}.png" alt="State-Transition Diagram {$IDX}."
/></a>
    {$END_LOOP}
   </detview-section>
   <detview-section name="Deployment Diagrams">
    {$BEGIN_LOOP}
    <a name="DEPLOY_{$ID_UPPERCASE}_{$IDX}"><img src="./diags/deploy/{$ID_UPPERCASE}_d{$IDX}.png" alt="Deployment Diagram {$IDX}."
/></a>
    {$END_LOOP}
   </detview-section>
   <detview-section name="Screen Layouts">
    {$BEGIN_LOOP}
    <a name="SCREEN_{$ID_UPPERCASE}_{$IDX}"><img src="./diags/screen/{$ID_UPPERCASE}_fig_{$IDX}.png" alt="Screenshot: {$IDX}" /></a>
    {$END_LOOP}
   </detview-section>
  </section>
 </body>
</document>
- - -

Does anyone have recommendations or counterproposals for which 'sections' should
be present in the design documentation?

Derek Harmon

edocs-development Mailing List for edocs

edocs-development — Developers mailing list