-
Notifications
You must be signed in to change notification settings - Fork 15
Expand file tree
/
Copy path10-documentation.html
More file actions
373 lines (317 loc) · 15 KB
/
Copy path10-documentation.html
File metadata and controls
373 lines (317 loc) · 15 KB
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
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>CS 4970: 10-documentation slide set</title>
<meta name="description" content="A set of slides for UVa's Service Learning Practicum course">
<meta name="author" content="Aaron Bloomfield">
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">
<link rel="stylesheet" href="../slides/reveal.js/css/reveal.css">
<link rel="stylesheet" href="../slides/reveal.js/css/theme/black.css" id="theme">
<link rel="stylesheet" href="../slides/css/slp.css">
<!-- Code syntax highlighting -->
<link rel="stylesheet" href="../slides/reveal.js/lib/css/zenburn.css">
<!-- Printing and PDF exports -->
<script>
var link = document.createElement( 'link' );
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = window.location.search.match( /print-pdf/gi ) ? '../slides/reveal.js/css/print/pdf.css' : '../slides/reveal.js/css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>
<!--[if lt IE 9]>
<script src="../slides/reveal.js/lib/js/html5shiv.js"></script>
<![endif]-->
<script type="text/javascript" src="../slides/js/dhtmlwindow.js"></script>
<script type="text/javascript" src="../slides/js/canvas.js"></script>
<link rel="stylesheet" href="../slides/css/dhtmlwindow.css" type="text/css">
</head>
<body>
<div id="dhtmlwindowholder"><span style="display:none"></span></div>
<div class="reveal">
<!-- Any section element inside of this container is displayed as a slide -->
<div class="slides">
<section data-markdown><script type="text/template">
# CS 4970
### Capstone Practicum I
<center><small>[Aaron Bloomfield](http://www.cs.virginia.edu/~asb) / [aaron@virginia.edu](mailto:aaron@virginia.edu) / [@bloomfieldaaron](http://twitter.com/bloomfieldaaron)</small></center>
<center><small>Repository: [github.com/aaronbloomfield/slp](http://github.com/aaronbloomfield/slp) / [↑](index.html) / <a href="10-documentation.html?print-pdf"><img class="print" width="20" src="images/print-icon.png"></a></small></center>
## Documentation
</script></section>
<section data-markdown><script type="text/template">
# Contents
[UML](#/uml)
[Use Cases & User Stories](#/usecases)
[Misc Documentation](#/misc)
[Conclusions](#/conclusions)
</script></section>
<section>
<section data-markdown id="uml"><script type="text/template">
# UML
</script></section>
<section data-markdown><script type="text/template">
## When to use UML
- When you need to clarify something through diagrams!
- Typically used with bigger development groups, or when two separate groups' code need to interact
- Don't write UML diagrams just for the sake of writing UML diagrams...
</script></section>
<section data-markdown><script type="text/template">
## UML diagrams diagram (!)
<a href="http://commons.wikimedia.org/wiki/File:Uml_diagram.svg"><img alt="uml diagram diagram" src="http://upload.wikimedia.org/wikipedia/commons/7/74/Uml_diagram.svg" style="background-color:white"></a>
(Object diagrams are now Domain model diagrams)
</script></section>
<section>
<h2>UML diagram types</h2>
<table class="transparent"><tr><td class="top">
<ul><li style="text-align:left">Structure diagrams<ul>
<li style="text-align:left">Class diagram</li>
<li style="text-align:left">Component diagram</li>
<li style="text-align:left">Composite structure diagram</li>
<li style="text-align:left">Deployment diagram</li>
<li style="text-align:left">Domain model diagram</li>
<li style="text-align:left">Package diagram</li></ul></li></ul></td>
<td style="width:50px"></td>
<td><ul><li style="text-align:left">Behaviour diagrams<ul>
<li style="text-align:left">Activity diagram</li>
<li style="text-align:left">Use case diagram</li>
<li style="text-align:left">State diagram</li>
<li style="text-align:left">Sequence diagram</li>
<li style="text-align:left">Communication diagram</li>
<li style="text-align:left">Interaction overview diagram</li>
<li style="text-align:left">Timing diagram</li>
</ul></li></td></tr></table>
</section>
<section data-markdown><script type="text/template">
## Sources
- A few diagram images are from Wikipedia (or Wikicommons)
- Most are from http://www.uml-diagrams.org/
- These images are not part of the repo, as their licenses do not provide for that
- So this slide set just deep links to those imags
- That site has a lot of information, far beyond what is in this lecture set
- In all cases, the title is the hyperlink to the source page, to allow for the image to be the largest size possible
</script></section>
<section>
<h2><a href="http://www.uml-diagrams.org/class-diagrams-overview.html">Class diagram</a></h2>
<img src="http://www.uml-diagrams.org/class-diagrams/class-diagram-implementation-elements.png" class="stretch" alt="class diagram">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/component-diagrams.html">Component diagram</a></h2>
<img src="http://www.uml-diagrams.org/component-diagrams/component-diagram-overview.png" class="stretch" alt="component diagram">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/composite-structure-diagrams.html">Composite structure diagram</a></h2>
<img src="http://www.uml-diagrams.org/composite-structure-diagrams/composite-internal-structure-diagram-elements.png" class="stretch">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/deployment-diagrams-overview.html">Deployment diagram</a></h2>
<img alt="deployment diagram" src="http://www.uml-diagrams.org/deployment-diagrams/deployment-diagram-overview-specification.png">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/class-diagrams-overview.html">Domain model diagram</a></h2>
<img class="stretch" src="http://www.uml-diagrams.org/class-diagrams/class-diagram-domain-overview.png" alt="domain model diagram">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/package-diagrams-overview.html">Package diagram</a></h2>
<img alt="package diagram" src="http://www.uml-diagrams.org/package-diagrams/package-diagram-elements.png" class="stretch">
</section>
<section>
<h2><a href="http://commons.wikimedia.org/wiki/File:Activity_conducting.svg">Activity diagram</a></h2>
<img src="http://upload.wikimedia.org/wikipedia/commons/e/e7/Activity_conducting.svg" class="stretch" style="background-color:white" alt="activity diagram">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/use-case-diagrams.html">Use case diagram</a></h2>
<img src="http://www.uml-diagrams.org/use-case-diagrams/business-use-case-diagram-elements.png" alt="use case diagram" class="stretch">
</section>
<section>
<h2><a href="http://commons.wikimedia.org/wiki/File:UML_State_diagram.svg">State diagram</a></h2>
<img src="http://upload.wikimedia.org/wikipedia/commons/2/2f/UML_State_diagram.svg" alt="state diagram" class="stretch" style="background-color:white">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/sequence-diagrams.html">Sequence diagram</a></h2>
<img src="http://www.uml-diagrams.org/sequence-diagrams/sequence-diagram-overview.png" class="stretch" alt="sequence diagram">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/interaction-overview-diagrams.html">Interaction overview diagram</a></h2>
<img alt="interactin diagram" src="http://www.uml-diagrams.org/notation/uml-interaction-overview-diagram-elements.png" class="stretch">
</section>
<section>
<h2><a href="http://www.uml-diagrams.org/timing-diagrams-examples.html">Timing diagram</a></h2>
<img src="http://www.uml-diagrams.org/examples/timing-diagram-example-website.png" class="stretch" alt="timing diagram">
</section>
</section>
<section>
<section data-markdown id="usecases"><script type="text/template">
# Use Cases &<br>User Stories
</script></section>
<section data-markdown><script type="text/template">
## User stories
> a user story is one or more sentences in the everyday or business language of the end user or user of a system that captures what a user does or needs to do as part of his or her job function
- from [Wikipedia](http://en.wikipedia.org/wiki/User_story)
</script></section>
<section data-markdown><script type="text/template">
## Use cases
- Just a prose (i.e. English) explanation of what's happening
- Play a dice game: player requests to roll the dice. System presents results: if the dice face value totals seven, player wins; otherwise, player looses.
- Three types:
- Brief: one-paragraph summary (like the one 2 slides ago) that covers the 'happy path'
- This is like a user story
- Casual: multiple-paragraph format that covers multiple scenarios
- Fully dressed: highly detailed
</script></section>
<section>
<h2>Fully dressed use case</h2>
<p>Alistair Cockburn <a href="http://www.amazon.com/dp/0201699699">describes</a> the following fields:</p>
<p> </p>
<table class="transparent"><tr>
<td style="width:45%">
<ul>
<li style="text-align:left">Title: "an active-verb goal phrase that names the goal of the primary actor"</li>
<li style="text-align:left">Primary Actor</li>
<li style="text-align:left">Goal in Context</li>
<li style="text-align:left">Scope</li>
<li style="text-align:left">Level</li>
<li style="text-align:left">Stakeholders & interests</li>
<li style="text-align:left">Precondition</li>
</ul></td><td style="width:10%"></td><td class="top" style="width:45%"><ul>
<li style="text-align:left">Minimal Guarantees</li>
<li style="text-align:left">Success Guarantees</li>
<li style="text-align:left">Trigger</li>
<li style="text-align:left">Main Success Scenario</li>
<li style="text-align:left">Extensions</li>
<li style="text-align:left">Technology & Data Variations List</li>
<li style="text-align:left">Related Information</li>
</ul></td></tr></table>
<p> </p>
<p>I have a 4-page example. Want to see it?<?p>
</section>
<section data-markdown><script type="text/template">
## UML for use cases
- Use cases are primarily text!
- However, you may often see a diagram that shows how the use cases *interact*
- The use case diagram from earlier in this slide set (and repeated next slide) is such an example
</script></section>
<section>
<h2><a href="http://www.uml-diagrams.org/use-case-diagrams.html">Use case diagram</a></h2>
<img src="http://www.uml-diagrams.org/use-case-diagrams/business-use-case-diagram-elements.png" alt="use case diagram" class="stretch">
</section>
<section data-markdown><script type="text/template">
## Actors
- Some 'thing' with a behavior
- A person, computer system, organization, etc.
- Three types
- Primary actor
- Supporting actor
- Offstage actor
</script></section>
<section data-markdown><script type="text/template">
## Use case writing guidelines
- Write in an essential UI-free style
- Write terse use cases
- Write black-box use cases
- Take an actor and actor-goal perspective
- Finding use cases
</script></section>
<section data-markdown><script type="text/template">
## Use cases: the big picture
- The waterfall method defines all the use cases up front
- Agile development methods define them over time
- And they are refined iteratively
</script></section>
</section>
<section>
<section data-markdown id="misc"><script type="text/template">
# Miscellaneous<br>Documentation
</script></section>
<section data-markdown><script type="text/template">
## Buzzword alert: artifacts
- An 'artifact' (as far as the Unified Process is concerned) is a document that defines some aspect of the development
- Wikipedia [defines](http://en.wikipedia.org/wiki/Artifact_%28software_development%29) them as the "tangible by-products produced during the development of software"
- Examples: Vision, Business Case, Use-Case Model, Supplementary
Specification, Glossary, Business Rules, Risk List, Risk Management
Plan, Prototypes, Iteration Plan, Phase Plan, Software Development
Plan, Development Case, etc.
</script></section>
<section data-markdown><script type="text/template">
## Vision
Sections of a vision statement:
- Introduction and product description
- Positioning
- Business opportunity
- Problem statement
- Product position statement
- Stakeholder descriptions
- Product overview
- Summary of system features
- Other requirements and constraints
</script></section>
<section>
<h2>Supplementary Specification</h2>
<p>This includes anything specifications not covered in a use case. Possible sections:</p>
<table class="transparent"><tr>
<td style="width:40%" class="top"><ul>
<li style="text-align:left">Introduction</li>
<li style="text-align:left">Functionality</li>
<li style="text-align:left">Usability</li>
<li style="text-align:left">Reliability</li>
<li style="text-align:left">Performance</li>
<li style="text-align:left">Supportability</li>
<li style="text-align:left">Implementation constraints</li>
</ul></td><td style="width:10%"></td><td style="width:50%"><ul>
<li style="text-align:left">Purchased components</li>
<li style="text-align:left">Free open source components</li>
<li style="text-align:left">Interfaces</li>
<li style="text-align:left">Application-specific domain (business) rules</li>
<li style="text-align:left">Legal issues</li>
<li style="text-align:left">Information in domains of interest</li>
</ul></td></tr></table>
</script></section>
<section data-markdown><script type="text/template">
## Glossary
- Includes (among other things):
- Definitions
- A data dictionary: Metadata
- And, not surprisingly, it evolves over time...
</script></section>
<section data-markdown><script type="text/template">
## Domain (business) rules
- These rules dictate how a domain (or business) may operate
- Such as laws, regulations, policies, etc.
- Example: a cashier system will need to know how sales tax is calculated, and on what times (i.e., not food)
</script></section>
</section>
<section>
<section data-markdown id="conclusions"><script type="text/template">
# Conclusions
</script></section>
<section data-markdown><script type="text/template">
## What's Missing?
- Only a few critical things...
- User manual
- Installation manual
- Licensing document
- Guide to the code for future developers & maintainers
</script></section>
<section data-markdown><script type="text/template">
## When to use all of this
- Here, "this" means either UML diagrams or documentation
- Some companies write a *lot* of documentation
- These tend to be more waterfall-based development shops
- Sometimes with good reasoan, but not always
- My philosophy is you only use it when you need it to clarify something
- That doesn't mean you avoid it at all costs!
</script></section>
</section>
</div>
</div>
<script src="../slides/reveal.js/lib/js/head.min.js"></script>
<script src="../slides/reveal.js/js/reveal.js"></script>
<script src="../slides/js/settings.js"></script>
</body>
</html>