Menu
▾
▴
[Edocs-development] Proposed design docs format
|
From: Derek H. <lor...@ms...> - 2002-11-18 03:03:04
|
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
|
