-
Notifications
You must be signed in to change notification settings - Fork 0
/
BlogOCD.html
279 lines (269 loc) · 14.8 KB
/
BlogOCD.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
<!DOCTYPE html>
<html>
<!--
BlogGlobals.html
-->
<head>
<title>Blog OCD</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- <link rel="icon" type="image/x-icon" href="./images/favicon.ico" /> -->
<link rel="stylesheet" href="css/StylesPhoto.css" />
<link rel="stylesheet" href="css/StylesSizerComp.css" />
<!-- PageFrame infrastructure -->
<link rel="stylesheet" href="css/StylesPageFrameDefaults.css" />
<link rel="stylesheet" href="css/StylesPageFrameStructure.css" />
<link rel="stylesheet" href="css/StylesPageFrameMenus.css" />
<link rel="stylesheet" href="css/StylesPageFrameThemePython.css" />
<link rel="stylesheet" href="css/StylesWebComponents.css" />
<script src="js/ScriptsWebComponents.js"></script>
<!--<script src="js/ScriptsPageFrameDefaults.js"></script>-->
<script src="js/ScriptsPageFramePosts.js"></script>
<script src="js/ScriptsPageFramePagesPosts.js"></script>
<script src="js/ScriptsPageFrameKeyboard.js"></script>
<!-- No need for Pages script for pages with no next or prev pages -->
<!--<script src="js/ScriptsPageFramePages.js"></script>-->
<!-- <script src="js/ScriptsTemplate.js"></script>
<link rel="stylesheet" href="css/StylesTemplate.css" /> -->
<style>
h3 {
margin-top: 1.5em;
}
#subtitle {
margin-top: 0.4em;
margin-bottom: 0.3em;
}
#github header summary {
border: 1px solid var(--light);
}
#github summary {
padding-right: 2em;
}
/* #github .menuHead {
margin:0em -0.25em 0.0em -0.25em;
padding:0.25em 0.5em;
} */
</style>
<script>
function load() {
initialize();
//loadif();
}
</script>
<style>
#github note {
display: block;
width:max-content;
border:1px solid red;
padding:0.5em 1.0em;
margin:0.5em 0em;
}
#github .bargraph {
border: 1px solid var(--dark);
/* background-color: #bbb; */
padding: 0.1em 0.5em;
font-size:0.9em;
}
#github table {
border:2px solid var(--dark);
}
#github table td {
padding:0.25em 1.0em;
/* border:none; */
}
body {
user-select:none;
}
</style>
<script>
function clickstat() {
// prevent parent click event handling
event.stopImmediatePropagation();
}
</script>
</head>
<body id="github" onload="load()" style="position:relative;">
<a id="Next" href="BlogTesting.html">Next</a>
<a id="Prev" href="BlogGlobals.html">Prev</a>
<page-frame>
<frame-header>
<nav id="navbar"></nav>
</frame-header>
<main id="main">
<div id="about" onclick="this.style.display = 'none'">about</div>
<div id="page">Blog: OCD</div>
<div id="modified">11/26/2024</div>
<div id="hlp"></div>
<a id="top"></a>
<content style="height:100vh; position:relative;">
<header style="cursor:pointer;" onclick="loadif()">
<!-- <a target="_blank" class="repoLink" href="https://github.com/JimFawcett">github Repositories</a> -->
<hgroup id="pagetitle" style="border: 2px solid var(--dark);">
<h1 id="title">Blog: Operational Concept Document (OCD)</h1>
<h3 class="indent" id="subtitle">
concept for system operations
</h3>
</hgroup>
<!-- <img style="width:100%; margin:-0.1em 0em; border:2px solid var(--dark); padding:0.5em; background-color:var(--light);" src="Pictures/officestrip3a.svg" /> -->
<div class="darkItem" onclick="loadif()" style="cursor:pointer; position:relative; padding:0.0em 0em 0.25em 0em; margin-top:-0.50em; border:2px solid var(--dark);">
<a class="repoLinks" target="_blank" href="https://github.com/JimFawcett" style="color:var(--atten); margin-left:1.5em;">About</a>
<div style="font-size:0.9em; position:absolute; top:0.1em; right:1.5em;">click to toggle Site Explorer</div>
<div style="height:0.5em;"></div>
</div>
</header>
<h3>1.0 Initial Thoughts:</h3>
<t-b>
An operational concept focuses on users, usability, product goals, and important risks. This post
considers how a project concept will integrate with its other documentation.
</t-b>
<h4 id="scale">1.1 Scale to Project Size</h4>
<t-b>
Sofware documentation should be scaled according to the size of the development team
and use of the product - more documentation for critical production software.
</t-b>
<table>
<tr>
<th class="banner">Team Size</th><th class="banner">Documentation Size</th>
</tr>
<tr>
<td>one or two developers</td>
<td>All documents consist of one to a few pages, may be captured in code comments.</td>
</tr>
<tr>
<td>small team (5 devs)</td>
<td>Concept and test document, specification and design may be captured in comments.</td>
</tr>
<tr>
<td>large team (50 devs)</td>
<td>All stand-alone documents with emphasis on interfaces and functionality.</td>
</tr>
<tr>
<td>multiple teams (200 devs)</td>
<td>Carefully written stand-alone documents with legal status for acceptance.</td>
</tr>
</table>
<t-b>
</t-b>
<h4 id="doctypes">1.2 Document Types</h4>
<t-b>
We normally think of software documentation being composed of Specifications, Design Documents, Test Plans, and Test Results. The idea is that Specifications should serve
to define the operation of it's associated software. Design documents describe the way it is built, e.g., its design and packaging. Test Plans describe how the software
will be tested for acceptance. Those tests are constructed to show that all of the specified behaviors and properties are satisfied by the implementation.
</t-b>
<ul class="indent">
<li>
<span class="em">Specifications:</span><br />
Define software product behavior and properties, are complete, unambiguous, and as brief and clearly stated as possible. We often, naively expect specifications to be immutable.
</li>
<li>
<span class="em">Design Documents:</span><br />
Describe the product as built. Support maintenance and provide a starting point for later versions. Usually describe the packages, classes, and data flow in the application.
May explain algorithms that are used and the functions that implement them.
</li>
<li>
<span class="em">Test Plans and Results:</span><br />
A Test Plan provides unambiguous descriptions of how each specification requirement is to be tested. Each description has one or more test procedures that provide
step-by-step instructions for testing. These must be clear enough that any knowledgeble person who probabaly did not write the software can successfully conduct each test.
If a test fails that shows that either the software or the test procedure has one or more errors.
</li>
</ul>
<t-b>
Managing projects with this set of documentation has one problem that may be significant for large or complex projects. Requirements are almost never entirely immutable.
Neither the customer nor the development team have perfect foresight when they write specifications. As the project proceeds we discover omissions, unnecessary embelishments,
and failures of concept. We usually discover these things as the product is being constructed and that causes rework of specification, design, and test procedures.
</t-b>
<t-b>
A development team needs some immutable concept to keep the project on track when these things happen. The project concept provides a coherent description of what the users expect,
describes the main pieces of the product and their responsibilities, and it enumerates areas of risk that get a lot of focus at the beginning of developement to minimize major rework later.
</t-b>
<h3 id="ocd">Operational Concept Document (OCD):</h3>
<t-b>
A few engineering organizations write Concept Documents while creating proposals to provide the basis for customer negotiation, to help estimate development costs, and to provide common
goals for all the development teams. I worked for many years on Radar software where concept documents were commonly used for these purposes. In CSE681 - Software Modeling and Analysis
we write concept documents before implementing required software projects. Perhaps our students will carry this practice into their own professional work.
</t-b>
<t-b>
An Operational Concept Document has this structure:
<ul class="indent">
<li>
<span class="em">Executive Summary:</span><br />
Gives a brief summary of the concept and most important risks.
</li>
<li>
<span class="em">Uses:</span><br />
An analysis of the product's users and their uses. What are the user's goals? What tasks do they execute and what data do they need to supply and retrieve? What is the impact
on product design to satisfy these user needs? Here is an <a target="_blank" href="Resources/ProjectCenterUseCases.pdf">example analysis of uses</a> for a software development
environment built out of a federation of open source tools, called the Project Center.
</li>
<li>
<span class="em">Partitions:</span><br />
Describes the major packages and their responsibilities, activities, and interactions.
</li>
<li>
<span class="em">Critical Issues:</span><br />
Enumerates significant risk areas and proposes solutions. Typical risks are complexity of parts and data flow, poor usability, potential for security breaches, inadequate performance,
potential loss of information, and loss of life or wealth. Obviously a flight navigation system has different risks than a software analysis tool. The assessment of risk is tuned
to the context of the application.
</li>
</ul>
</t-b>
<h3 id="thoughts">Thought Process:</h3>
<t-b>
One purpose of the Operational Concept Document is to encourage critical thinking about a project before committing to code. Uses, partitions, and critical issues describe the main
areas of focus, but our thinking should be more nuanced than just a direct assault on these topics. We want to explore, at an abstract level, our options for design and implementations,
consider ways in which the project could be extended for future products so our design doesn't make that more difficult than necessary. And finally we want to convince ourselves and
the rest of the development team that the project goals are attainable with reasonable effort, time, and expertise. The discussion in the
<a href="BlogNoSql.htm">noSQL blog</a> is a good example of how these thought processes work.
</t-b>
<h3>An Example:</h3>
<t-b>
In <a href="https://ecs.syr.edu/faculty/fawcett/handouts/webpages/cse681.htm">CSE681 - Software Modeling and Analysis</a>, Spring 2010, the final project goal was to develop an Operational Concept Document for a large distributed Quality Assurance
Toolset deployment system. One of the students, John Walthour, a part-time student working full time as a software developer, wrote a fine example of what an OCD should be. I'm pleased,
with his permission, to provide a link to that <a target="_blank" href="Resources/jwalthour-pr5.pdf">excellent piece of work</a>. Look at the document table of contents to see one very good
way of organizing the structure of an OCD. And pay particular attention to John's discussion of critical issues. That discussion is totally appropriate for the context of his application
and he suggests effective ways of addressing most of the issues.
</t-b>
<h3>Note:</h3>
<t-b>
The "Initial Thoughts" discussion sounds a lot like a sequential "Waterfall" development model. Note, however, that the agile processes and spiral models each
contain several segments which have small sequential Spec-Design-Code-Test cycles (although extreme programming merges Test with Design). The process of clearly documenting the overall project
concept at the beginning is important for any of these development models.
</t-b>
<div style="height:1em;"></div>
<img class="photo" src="Pictures/campusstrip4.jpg" alt="Newhouse" style="width:calc(100vw - 9em);" />
<t-b>
<div style="height:1em;"></div>
<a id="bottom"></a>
</content>
<page-TOC id="pages" style="display:none;">
</page-TOC>
<page-sections id="sections" style="display:none;">
<menu-elem style="width:0.0em"> </menu-elem>
<menu-elem class="secElem"><a href="#bottom">bottom</a></menu-elem>
<menu-elem class="secElem"><a href="#thoughts">thoughts</a></menu-elem>
<menu-elem class="secElem"><a href="#ocd">OCD</a></menu-elem>
<menu-elem class="secElem"><a href="#doctypes">doctypes</a></menu-elem>
<menu-elem class="secElem"><a href="#scale">scale</a></menu-elem>
<menu-elem class="secElem"><a href="#top">top</a></menu-elem>
<div class='darkItem popupHeader' style="padding:0.25em 2.0em;" onclick="this.parentElement.style.display='none'">Sections</div>
</page-sections>
</main>
<frame-footer>
<menu-item style="width:2.0em;"> </menu-item>
<menu-elem id="nextLink2" onclick="bottomMenu.next()">Next</menu-elem>
<menu-elem id="prevLink2" onclick="bottomMenu.prev()">Prev</menu-elem>
<menu-elem id="pgbtn" onclick="bottomMenu.pages()">Pages</menu-elem>
<menu-elem onclick="bottomMenu.sections()">Sections</menu-elem>
<menu-elem onclick="bottomMenu.about()">About</menu-elem>
<menu-elem id="kysbtn" onclick="storyHlpMenu.keys()">Keys</menu-elem>
<menu-elem style="margin-right:1em">
<span id="loc" style="display:inline-block; font-weight:normal"></span>
</menu-elem>
</frame-footer>
</page-frame>
<script>
let loc = document.getElementById("loc");
let fn = window.location.href.split(/\/|\\/).pop();
loc.innerHTML = fn + ":";
</script>
</body>
</html>