-
Notifications
You must be signed in to change notification settings - Fork 15
Expand file tree
/
Copy path11-deliverables.html
More file actions
986 lines (844 loc) · 46.3 KB
/
Copy path11-deliverables.html
File metadata and controls
986 lines (844 loc) · 46.3 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
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>CS 4971: 11-deliverables 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 4971
### Capstone Practicum II
<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="11-deliverables.html?print-pdf"><img class="print" width="20" src="images/print-icon.png"></a></small></center>
## Deliverables
</script></section>
<section data-markdown><script type="text/template">
#Contents
[Introduction](#/introduction)
[Transition Plan](#/transition)
[User Manual](#/usermanual)
[Installation Instructions](#/installation)
[Programming Reference](#/progref)
[Requirements Document](#/reqsdoc)
[STS Technical Report](#/stsreport)
[Final Presentation](#/finalpres)
[Miscellaneous Deliverables](#/misc)
[Tutorials](#/tutorials)
[Submission Requirements](#/submission)
[Conclusion](#/conclusion)
</script></section>
<section>
<section id="introduction" data-markdown><script type="text/template">
# Introduction
</script></section>
<section data-markdown><script type="text/template">
## Non-documentation deliverables
- A working, installed, and deployed system built to the customer's requirements
- Obviously...
- Source code in electronic format
- In the `master` branch of the github repo
- All other branches should be merged and removed by the end of the school year
- Emailed as a .zip file to the customer
- Details about that are to be specified later
- The rest of the deliverables are documentation...
</script></section>
<section data-markdown><script type="text/template">
## Documentation artifacts to be produced
- Transition plan
- Including: deployment plan, installation instructions, master test plan, code coverage report
- User manual
- Programming reference
- Updated requirements document
- STS technical report
- Final presentation presentation
- Miscellaneous: screen shot(s) and a one-slide version
- Tutorial (individual, instead of a final exam)
</script></section>
<section data-markdown><script type="text/template">
## Size notes
- These don't have to be long-winded documents!
- For example, the installation instructions can be a single page
- But will probably be more for Rails...
- I don't want you to add fluff
- Having to read that just makes me cranky and wastes my time
- But it needs to be well English
</script></section>
<section data-markdown><script type="text/template">
## Lecture notes
- This slide set is (intentionally) very verbose because I want it to also serve as a reference throughout the rest of the semester when writing these artifacts
- So please excuse the fact that there is way too much text on the slides...
</script></section>
<section data-markdown><script type="text/template">
## Deliverable format
- All documents are to be in a `docs/` directory in the *root* of your github repo
- The documents need to be in either Markdown or PDF
- Most of the *internal* documents (ones mean for myself and the team) are to be in Markdown
- Anything that needs pretty formatting (user manual, etc.) should be in PDF
- If PDF, then the source (.docx, .tex, etc.) should be in there as well
- Name them something appropriate: `deployment-plan.md`, `transition-plan.pdf`, etc.
- The names are specified at the end of this document
</script></section>
<section data-markdown><script type="text/template">
## A note on quality
- We are not expecting you to spend days and days on each one
- But throwing something together at the last minute, and not putting an appropriate amount of effort into it, is not sufficient
- They must be reasonably good quality, else they will not be considered fulfilling of the requirement
</script></section>
</section>
<section>
<section id="transition" data-markdown><script type="text/template">
# Transition Plan
</script></section>
<section data-markdown><script type="text/template">
## Overview
- To be completed by the end of iteration 11 (March 27th), this will contain the necessary information for a proper transition
- The parts of the transition plan are developed over the next few iterations
- Audience: the development group
- The requirements document is not technically part of the transition plan, but the updated version is also due March 27th
</script></section>
<section data-markdown><script type="text/template">
## Sections
- Requirements document
- Technically not part of the transition plan...
- The full transition plan consists of:
1. Deployment plan
2. Installation instructions
3. Master test plan
4. Code coverage report
- The parts above are due at the end of iterations 7-10, respectively
- The full transition plan is due at the end of iteration 11
</script></section>
<section data-markdown id="deployment-plan"><script type="text/template">
## Deployment plan
- Due at the end of iteration 7 (January 30th)
- It should contain:
- Where the system is being deployed (URL, provider, etc.)
- Alternatively: AWS, Heroku, customer's machine, etc.
- What "things" need to be acquired for said deployment
- Servers? Domains? Hosting accounts? Credentials?
- Acknowledgment from the customer that s/he will need to acquire those "things"
- Details on next slide...
</script></section>
<section data-markdown><script type="text/template">
## Deployment plan: acknowledgment
- The acknowledgment from the customer
- This can be an e-mail separate from the deployment plan itself
- You should start (or continue) an email conversation with the customer about all this; said email conversation is likely sufficient
- And a rough time line for the acquisition of said "things"
</script></section>
<section data-markdown><script type="text/template">
## Deployment plan, part 2
- A single paragraph is fine, if that covers everything
- You should also include whatever indicators you have that the customer understands that s/he will have to acquire this, if appropriate (email snippet, for example)
- Many of you will need a couple of iterations to have this finalized; that's fine; just mention that in the deployment plan, and keep it updated
- This will likely be an edit of what you created last semester
- It should be in a docs/deployment-plan.md file in your repo
- If you name it something else, we won't be able to find it, and you won't get credit for it!
</script></section>
<section data-markdown><script type="text/template">
## Installation instructions
- Due at the end of iteration 8 (February 14th)
- Discussed [later in this slide set](#/installation)
</script></section>
<section data-markdown><script type="text/template">
## Code coverage report
- Due at the end of iteration 10 (March 13th)
- You already have a number of unit tests written, and it should be running on Travis or CircleCI
- You need to ask: do the unit tests cover *all* of the code?
- Each group will need to run a code coverage analysis tool, and report how much of the code base is covered
- There are two parts, both discussed in the [testing slide set](12-testing.html#/):
- [Main code coverage](12-testing.html#/codecoverage) for your Python / Ruby / PHP code
- [Javascript code coverage](12-testing.html#/jscodecoverage) for your Javascript code
- You will need to hit 100% code coverage by the end of iteration 12 (April 10th)
</script></section>
<section data-markdown><script type="text/template">
## Code coverage report
- Your *entire* code base needs to be (eventually) covered!
- Anything *not* covered will have to have an explanation as to why
- This means you will need to start writing lots of unit tests!
- Don't wait until the last minute to do this!
- It will be *far* easier to do this as you develop in the next few iterations
- This part of the transition plan is purposely the last part due to give you more time to develop the unit tests
- More details about code coverage will be forthcoming in the [testing slide set](12-testing.html) slide set
- That slide set is not yet ready, as it needs updates...
</script></section>
<section data-markdown><script type="text/template">
## Code coverage report updates
- At the end of *each* iteration, you will need to re-run the code coverage report
- This way, when we look at it after each iteration, it will be up-to-date with respect to the unit tests you have written
- It takes all of 2 minutes to run this report, once it's been set up and run the first time...
</script></section>
<section data-markdown><script type="text/template">
## Master test plan
- Due at the end of iteration 9 (February 28th)
- See the forthcoming [testing slide set](12-testing.html) for details
- That slide set is not yet ready, as it needs updates...
- This is a high-level overview of the testing
- From the point of view of the tests: which requirements are being tested?
- From the point of view of the requirements: what tests are validating that those requirements work?
- It also contains a list of all the types of tests you are going to perform
</script></section>
<section data-markdown><script type="text/template">
## Full transition plan
- Due at the end of iteration 11 (March 27th)
- This entails taking the four previous sections and updating them and making edits
- Example: as you will likely add more code in this iteration, you will be writing some more unit tests, and thus your code coverage report will have to be updated
- This will be turned in along with the updated requirements document
- It will thus contain:
- The road map for how to deploy the system
- A plan for the testing of the system
</script></section>
</section>
<section>
<section id="usermanual" data-markdown><script type="text/template">
# User Manual
</script></section>
<section data-markdown><script type="text/template">
## Overview
- This includes directions for how to use the system
- Audience:
- A new customer -- say, if your customer leaves, and a new one takes over -- who will need to learn how to use the system when they have NO prior knowledge
- The existing customer, to use as a reference
- But assume that the audience has NO technical knowledge
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 1
- For each feature of the system, instructions for how to use it
- If it's obvious, you can just explain it briefly
- If it's not obvious, then longer explanations and/or screen shots are appropriate
- Nobody wants to read fluff
- If your user manual is 2 pages and covers everything, that's fine
- Although I would be surprised if any were that short...
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 2
- Anything complicated will need sufficient explanation
- This includes explanations as to how the algorithms work (if knowing such affects the user)
- In particular, the scheduling algorithms
- Screen shots are likely going to be necessary for a proper explanation
</script></section>
<section data-markdown><script type="text/template">
## Format
- If PDF: letter page size, single spaced, reasonable margins, reasonable fonts
- If Markdown, you will need to ensure that this prints out properly
- Embedded images, word wrap, etc., do not format so well with Markdown
- Thus, the user manual will be more difficult to generate in Markdown (but not impossible)
</script></section>
<section data-markdown><script type="text/template">
## Sections
- This is just an example:
- Introduction
- Overview
- Description of each main "part" of the system
- Miscellaneous
- Conclusions (if necessary)
</script></section>
<section data-markdown><script type="text/template">
## And remember...
- Each of your user stories (or use cases) should be somehow covered in the manual
- So look over that requirements document!
</script></section>
<section data-markdown><script type="text/template">
## Links for writing the user manual
- [Tips for writing user manuals](http://www.userfocus.co.uk/articles/usermanuals.html)
- [How to Write User Manuals](http://www.wikihow.com/Write-User-Manuals)
- [How To Write a User's Manual](http://www.ehow.com/how_5140680_write-user-manual.html)
- Or just Google for "how to write a user manual"
- Those are the first three results from that search
- We also have a tutorial on [How to Write a Good User Manual](https://github.com/uva-slp/tutorials/blob/master/other/how-to-write-good-user-manual/index.md)
</script></section>
</section>
<section>
<section id="installation" data-markdown><script type="text/template">
# Installation<br>Instructions
</script></section>
<section data-markdown><script type="text/template">
## Overview
- This is actually part of the transition plan
- This should contain instructions for how to install the system
- Audience is the customer
- So do not assume that they have any technical knowledge beyond what you already know they have
- And don't really assume that much either -- a new customer with zero knowledge may have to install the system
- If the installation is easy, it can be a single page
- Some groups will have much longer installation instructions (Rails, in particular)
</script></section>
<section data-markdown><script type="text/template">
## Assumptions
- You can assume:
- They already have a system that runs Apache and MySQL (or they know how to install it)
- But you should include a quick note as to what packages would have to be installed if they choose to install it themselves
- Feel free to include the instructions from this repo on how to configure Apache; you can copy this all verbatim from the [VirtualBox image configured with LAMP](../docs/virtualbox-image-details.html) ([md](../docs/virtualbox-image-details.md)) page
- More assumptions on the next slide...
</script></section>
<section data-markdown><script type="text/template">
## More Assumptions
- You can assume:
- phpMyAdmin is installed (or they can install it) -- this is a single package on Ubuntu
- `sudo apt-get install phpmyadmin`
- That they are installing the software system (not the LAMP stack) from scratch (i.e., creating the database, etc.)
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 1
- How to create the account(s) that will host the file
- In Dreamhost or Bluehost, for example, a walk-through of the web pages to configure this
- Likewise for Heroku, AWS, or similar
- How to install any dependent packages
- apt-get installs, PHP libraries, Ruby gems, or Python libraries
- How to upload all the files from the system
- Have them download a free version of SecureCRT or similar
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 2
- How to configure those files
- They will need to update database.php or database.yml with the MySQL username, password, and DB
- They will need to `chmod 777 app/tmp` for CakePHP, for example
- How to initialize the database
- There should be a schema.sql (or similar) that they can upload to create the tables
- How to load any default values into the database
</script></section>
<section data-markdown><script type="text/template">
## Testing
- This will need to be tested!
- The 'installation testing' aspect of the master test plan
- More details in the [testing slide set](12-testing.html) slide set
- Given a BLANK VirtualBox image, or a BLANK Dreamhost or Bluehost account, do the instructions work?
- Note that the provided course image already has some of the installation commands completed!
</script></section>
<section data-markdown><script type="text/template">
## Installation instructions versus deployment plan
- The deployment plan has sufficient information for the *technical* members of the team to know where/how it will be deployed
- The installation instructions are for a *non-technical* customer who will need to re-install the system
- You have to include how to upload the files, how to configure things, etc.
</script></section>
</section>
<section>
<section id="progref" data-markdown><script type="text/template">
# Programming<br>Reference
</script></section>
<section data-markdown><script type="text/template">
## Overview
- This is a document intended to allow a *programmer* to modify the system
- Audience: a person who is (somewhat) knowledgeable in CakePHP, Rails, or Django, as appropriate
- The nonprofits may hire somebody to augment the system
- Or I may have to go in and fix something
- Or another team may take it over in the future
</script></section>
<section data-markdown><script type="text/template">
## Assumptions
- The intended audience knows a bit about CakePHP, Rails, or Django, as appropriate
- Enough to write a simple system
- But not necessarily a lot of in-depth knowledge
- That the audience has sufficient other technical knowledge
- MySQL, etc.
- They will read the schema.sql file along with these instructions
</script></section>
<section data-markdown><script type="text/template">
## What to include
- An overview of what goes where, design decisions made, how data is stored, etc.
- The purpose is so that a person familiar with CakePHP / Rails / Django can rapidly get up to speed with modifying the system without having to read through a lot of source code
- Did you use other components (CakePHP plugins, Rails gems, Python packages)?
- If so, discuss those as well
- You are welcome to include UML if it will help explain things, but it is by no means required
- See [last semester's documentation lecture](10-documentation.html#/) for the UML diagram details
</script></section>
<section data-markdown><script type="text/template">
## Consequences
- This means that your code will need to have some comments!
- In the non-obvious sections, especially
- We aren't necessarily talking about full-fledged doxygen comments
- Just enough so that the programmer can figure out what is going on
- However, this can all be provided via sufficient doxygen comments
- In this case, the programming reference will state how to generate said doxygen comments, and where to start reading
</script></section>
</section>
<section>
<section id="reqsdoc" data-markdown><script type="text/template">
# Requirements<br>Document
</script></section>
<section data-markdown><script type="text/template">
## Overview
- Your requirements document must be fully updated
- You are welcome to describe features that were not in the system (i.e., the "optional requirements"), but these must be in a clearly labeled section that indicates that they are not implemented
- Start with what was provided to you in September, and edit from there
- All the user stories (or use cases) of the system need to be in here
</script></section>
<section data-markdown><script type="text/template">
## Fully Updated!
- At the end of the semester, I will evaluate your system on two metrics relative to the requirements document:
1. Is everything in the requirements document in the system? And is everything in the system in the requirements document?
2. Is the updated document appropriate?
- Meaning if you change it to say only that the system will print "Hello World", and then implement that system, then that's not an appropriate requirements document
- This means that we need to chat about major edits to the requirements document
- There are other metrics that the system is going to be graded on, by the way
</script></section>
</section>
<section>
<section id="stsreport" data-markdown><script type="text/template">
# STS Technical Report
</script></section>
<section data-markdown><script type="text/template">
## Overview
- A group article that describes what you did this year
- Audience: a fellow computer scientist
- Imagine if it were going to a computer science conference
- ALL the members of the group will contribute to the report, even if you are not using this for your STS thesis
</script></section>
<section data-markdown><script type="text/template">
## Format
<table class="transparent"><tr>
<td class="top"><p> </p><ul><li>Two-column</li><li>Single spaced</li><li>Size 10 font</li><li>Standard margins</li><li>5-6 pages</li><li>That will be<br>somewhere<br>between<br>4,000 to 5,000<br>words</li></ul></td>
<td><img src="images/slp-article-first-page.png" alt="SLP paper first page"></td>
</tr></table>
</script></section>
<section data-markdown><script type="text/template">
## Format, take 2
- Templates available from [here](http://www.acm.org/sigs/publications/proceedings-templates) (use the "ACM_SigConf.docx" file in the Word download)
- Available in Word or LaTeX; your choice
- You are welcome to use a group editing system to develop it; just the final version must be in that format
- Reports not in that format will not be accepted nor signed!
- References must also be in that format
- LaTeX makes references VERY easy; Word is a pain
- For LaTeX, use [Google Scholar](http://scholar.google.com/) to look up a citation, and then cut-and-paste the BibTeX into a references.bib file
- I can explain more if you are interested...
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 1
- *Abstract*: a one paragraph summary of the entire article
- This is the one paragraph that everybody will read (and many will not read beyond it), so make it good!
- The abstract should give a compelling reason why your system is worthwhile.
- *Introduction*: Describe the nonprofit, the work they do, and the problem they face.
- How do they currently solve that problem (if they do solve it currently)?
- How long does it take?
- What problems does the current way of solving it cause?
- (continued next slide...)
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 2
- *Introduction*, continued
- We are setting the stage for how and why your system will be beneficial
- Likely a paragraph about the SLP course structure, STS project, etc.
- *Background*: What do they need to know to understand the system?
- Likely information about the domain that it's in, as well as the technologies used (CakePHP / Rails / Django, in particular)
- (continued next slide...)
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 3
- *Background*, continued
- Recall that the audience are computer scientists! So you don't need to give more than a single sentence describing CakePHP or Rails
- If all you are saying is that CakePHP / Rails / Django was used, you can stick that into the introduction
- *Related work*: what other systems exist that do similar things? Are they custom written, or generic? Why don't they fit the bill?
- This gives a context of what else is out there, so that one can understand where your system fits into everything
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 4
- *System design*: how was the system designed?
- This should focus on two primary aspects:
- Overall system architecture (no low-level details!)
- Followed by interesting/challenging/etc. design decisions
- This will likely be the largest section, likely also with sub-sections
- *Procedure* (if appropriate)
- How does the customer use the system? How do other stakeholders use the system?
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 5
- *Results*
- The system solved some problem – what are the results of that?
- Example: "The scheduler allowed the customer to prepare a schedule in 30 minutes, where it took 3 hours before"
- This will require **ACTUAL** numbers (ideally measured)
- *Conclusions*
- Summarize your article and your work
- "We designed a system to meet the need of nonprofit X"
- Summarize (and repeat) the relevant results that make the system look good
</script></section>
<section data-markdown><script type="text/template">
## Sections, part 6
- *Future work*
- If you had a full-time job for an entire year to work on this system -- and only this system -- what features would you add?
- *Acknowledgments*
- Likely the customer you worked with.
- Not me!
- *References*
- They need to look like the references in the LaTeX template, although you can also do that in Word
</script></section>
<section data-markdown><script type="text/template">
## Other stuff to include
- Feel free to add (or remove) sections -- what is listed here are just suggestions
- Indeed, some of the sections are not appropriate for all groups
- Longer sections should include sub-sections
- Screen shots, images, etc., are fine -- but this is not a picture book, so use these sparingly
</script></section>
<section data-markdown><script type="text/template">
## Screen shots
- The article is not a picture book, but a screen shot or two is not unreasonable
- This will make it easier for the reader to visualize what is going on
- Total screen shot usage should not take up more than 1/2 page, total
</script></section>
<section data-markdown><script type="text/template">
## Things to remove
<table class="transparent"><tr>
<td class="top" width="63%">
<ul><li>In both templates (and especially the LaTeX version), there are a few items that we do not need:<ul>
<li>The license block (very bottom of the 1st column on the first page)</li>
<li>Categories and Subject Descriptions</li>
<li>General Terms</li>
<li>Keywords</li></ul></li>
<li>You can (and should) remove all of these.</li>
</ul></td>
<td><img src="images/slp-article-first-page.png" alt="SLP paper first page"></td>
</tr></table>
</script></section>
<section data-markdown><script type="text/template">
## Writing notes
- You should not be using individuals' names in the article
- Other than the author list and possibly the acknowledgments
- You may certainly refer to the nonprofit by name, of course
- It should always be written in the plural first tense
- "We did this", not "I did this"
- (This is true for single-author articles as well, by the way)
- Who did what is irrelevant for the purposes of this article; everything was done "by the group"
</script></section>
<section data-markdown><script type="text/template">
## Author list
- All authors should be listed
- The order is up to you, but I suggest alphabetically by last name
- There should be *exactly* two lines under your name:
- Your affiliation ("University of Virginia")
- Your email ("mst3k@virginia.edu")
- And nothing else! No cell numbers, no addresses, etc.
- Note that the additional authors section at the end should be ignored; put all the authors on the top of the front page
</script></section>
<section data-markdown><script type="text/template">
## Due date
- I need the articles ***two weeks*** before they are due to your STS instructor
- If group members have different deadlines, then it's two weeks before the *earliest* of those deadlines
- I will spend a week (or so) reading them over
- Yes, I read over and comment on each of them!
- But I have a number to read over, so I will need time to get through them all...
- And then you have a week to make any changes and then get all the signatures
</script></section>
</section>
<section>
<section id="finalpres" data-markdown><script type="text/template">
# Final Presentation
</script></section>
<section data-markdown><script type="text/template">
## Overview
- There will be a final presentation at the end of the semester
- One option is during the last few classes (this means showing up on Fridays!)
- Another option is during the final exam time slot, but we can't fit all the projects into that time
- Details about when to follow
- Audience: the rest of the class and the customers
- And other selected guests and big-wigs
- You will demo the system, the challenges you faced, etc.
- It is to be done by the entire group! And all group members must participate!
</script></section>
<section data-markdown><script type="text/template">
## The right attitude...
- Your presentation is meant to show what you have done throughout the semester
- You all will have put a LOT of work in to the system
- And have a LOT of work left to do...
- The presentation should show off how absolutely amazing the system is
- People should leave with a feeling of awe and wonder at your software engineering prowess
- This is a time to show off!
</script></section>
<section data-markdown><script type="text/template">
## Guidelines
- Part of this presentation is a demo of your system (on pegasus is fine)
- Presentations should be about 10 minutes each
- Due to the number of projects, we have to keep to that time limit!
- Everybody in the group should participate in some way; this is a group presentation
- This should be rehearsed, and flow smoothly
- If you were presenting such a project in front of your boss, you would not want to run into logistical problems during the presentation (such as, "wait, I thought *you* were talking about this part")
- Format is described [elsewhere in this slide set](#/finalpresformat)
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 1
- This is meant as a guide, not a fixed requirement
- And the order is meant as a guide as well
- Introduce all the group members (not everybody in the class knows everybody else)
- Give a quick introduction about what the project is (while everybody else read about them at the beginning of the semester, they may not remember the details of each project)
- Technologies used; possibly including licensing details, if relevant. Here, a "technology" is something that is an integral part of the system.
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 2
- Tools used (or things used well) - this could be efficient or innovative use of the provided tools (git, github, etc.), but is more likely going to be additional tools that you used
- Here, a "tool" is something that supports the development of the system, but is not part of it.
- Don't bother explaining to us what github is (or any other tool the rest of the class used)
- Challenges you faced while developing it
- Any significant requirements changes (either by the customer, or a change of the "minimum" or "desired" requirements)
- Keep in mind the customer may be present, so phrase it accordingly...
</script></section>
<section data-markdown><script type="text/template">
## What to include, part 3
- Any interesting testing information? Perhaps not...
- What you feel your system is good at; what it is not good at (or lacks)
- Screen shots: while we do want a demo of the system, you are welcome to describe much of the functionality using screen shots, if you would like
- Comments on things: what worked well, what didn't work well
- Things not appropriate for a presentation can instead go into the last end-of-year survey or the course evaluations
</script></section>
</section>
<section>
<section id="misc" data-markdown><script type="text/template">
# Miscellaneous<br>Deliverables
</script></section>
<section id="screenshots" data-markdown><script type="text/template">
## Screen shot(s)
- We want a few screen shot(s) of the system
- This is going to be used in advertising and publicity, so make it a good one!
- It SHOULD include the logo of the nonprofit in some way
- Name it `screenshot.png`, `screenshot-2.png`, etc.
- These need to be a "publicity shot" that shows off as much of your system as can be done in a single screen shot
</script></section>
<section id="singleslide" data-markdown><script type="text/template">
## Single slide
- A single slide about your system
- This is a one-shot description of your system, also to be used in advertising and publicity
- Make it a good slide!
- Slides with just text indicate a complete lack of caring about and indifference to... umm...
- This is also a "publicity" slide
- The intent is to merge all the slides into a single slide show to show off all that you have done
</script></section>
<section data-markdown id="finalpresformat"><script type="text/template">
## Format
- You are welcome to use any software that you want for your main presentation
- PowerPoint (from Microsoft Office), Impress (from LibreOffice), Keynote (Mac OS X), or reveal.js (what this slide set is in)
- If you want to use reveal.js, you can grab my slides as samples from the [github repo](https://github.com/aaronbloomfield/slp), or just clone the [reveal.js repo](https://github.com/hakimel/reveal.js/)
- However, the one-slide version ***MUST*** be in PowerPoint
- Sorry!
- It's too hard to stitch together slides of different formats
</script></section>
</section>
<section>
<section id="tutorials" data-markdown><script type="text/template">
# Tutorials
</script></section>
<section data-markdown><script type="text/template">
## Overview
- Everybody will create a tutorial on something
- Audience: your fellow students in the class
- As you think of topics throughout the semester, you should reserve them
- In the [uva-slp/tutorials wiki](https://github.com/uva-slp/tutorials/wiki) there is a [reservations page](https://github.com/uva-slp/tutorials/wiki/Reservations) where you should reserve your topics
- It's first-come first-serve
- Look over the tutorials in [uva-slp/tutorials](https://github.com/uva-slp/tutorials), as you can't duplicate something that is there
- This is in lieu of the final exam!
</script></section>
<section data-markdown><script type="text/template">
## Guidelines, part 1
- The intent is to write a tutorial on *something* that you had to work through this semester
- Something that, if you had had a tutorial ahead of time, would have saved you time or effort
- It must be something that there does not exist a tutorial already online
- They are due at the end of iteration 14 (Tuesday, May 9th by noon)
</script></section>
<section data-markdown><script type="text/template">
## Guidelines, part 2
- Basically, we want to ensure that you develop a quality tutorial that can be used by future students
- All the tutorials must be developed in the [uva-slp/tutorials](https://github.com/uva-slp/tutorials) repo (details shortly)
- Preference would be for each tutorial to be on one page (i.e. no sub-pages), if possible
- Tutorials should have embedded images, screen shots, code segments, etc., as appropriate.
- You are welcome to build upon existing online tutorials, but you must also cite them as well
- However, we do NOT want you just duplicating an existing online tutorial
</script></section>
<section data-markdown><script type="text/template">
## Guidelines, part 3
- I may allow conversion of old tutorials at some point, but as of now that is not an option
- Note that conversion means making sure that it still works!
- The format will be [Markdown](https://help.github.com/articles/markdown-basics/)
- There is a repo that everybody will fork: [uva-slp/tutorials](https://github.com/uva-slp/tutorials)
- The [README.md](https://github.com/uva-slp/tutorials/blob/master/README.md) contains instructions for topic reservation and how to submit the tutorial (which is done via a [pull request](https://help.github.com/articles/creating-a-pull-request/))
- This is meant to take about 3 hours, which is the time a final exam would take
</script></section>
<section data-markdown><script type="text/template">
## Guidelines, part 4
- This will count in lieu of your final exam, which will be a non-insignificant part of your final grade
- In an effort to keep this sane for us, will are going to insist that you please follow the directions laid out in that tutorial
</script></section>
<section data-markdown><script type="text/template">
## Logistics
- If allowed, the list of tutorials to convert will be updated later in the semester
- We want the tutorials to be quality pieces of work
- We don't intend for you to have to spend weeks developing it
- But a quick rush-job is not what we are looking for either
- Tutorials will be graded!
</script></section>
</section>
<section>
<section id="submission" data-markdown><script type="text/template">
# Submission<br>Requirements
</script></section>
<section data-markdown><script type="text/template">
## Consistency requirements
- For the final submission, the documentation files will need to be named something consistent
- Basically, you need to include all the documents that have been created this year
- This should not be particularly onerous (it's really just renaming files), and should take all of 5 minutes...
- Any notes on the documentation will be included in a `docs/readme.md` file (discussed later)
</script></section>
<section data-markdown><script type="text/template">
## Documentation submission
- All documents should be in a `docs/` directory in your github repo
- If the files are PDFs, then you ***MUST*** include the original source files (.docx, .tex, etc)
- LaTeX documents may need sub-directories of supporting images, etc.
- If they were generated via an online editor (Google Drive or similar), then export it to an editable format (.docx, .odt, etc.), and note this in the readme.md
</script></section>
<section data-markdown><script type="text/template">
## Documentation submission, cont'd
- Stuff to include:
- user-manual.pdf: the Markdown or PDF version of the user manual
- installation-instructions.md/pdf: the installation instructions (actually part of the transition plan, mentioned on the next slide also)
- programming-reference.md/pdf: the programming reference
- If it's part of the code base (such as doxygen comments), then there should still be a programming-reference.md/pdf file that states this (and has quick directions how to generate said documentation)
</script></section>
<section data-markdown><script type="text/template">
## Documentation submission, cont'd
- More contents to include:
- technical-report.pdf: what you turned in for your STS thesis
- requirements-document.md: what was completed at the end of iteration 11
- Transition plan documents: what you developed in iterations 7-10
- deployment-plan.md
- installation-instructions.md
- master-test-plan.md
- coverage/index.html (code coverage report, described [here](12-testing.html#/codecoverage))
- specific-test-plan.md
</script></section>
<section data-markdown><script type="text/template">
## Documentation submission, cont'd
- More contents to include:
- Final presentation materials
- final-presentation.XXX: Final presentation slide set
- final-presentation.pdf: a PDF version of your presentation (one slide per page), as I may not have access to the program that you used to create your slide set
- one-slide.pptx: the 'one slide' marketing version
- screenshot.png: the screenshot(s)
- They can be .png, .jpg, etc. And feel free to include more than one; just number them sequentially
- Any supporting files (files and images needed to make LaTeX compile, etc.)
</script></section>
<section data-markdown id="readmemd"><script type="text/template">
## Documentation submission, cont'd
- More contents to include:
- readme.md: this should any explanations about where files (for online files) are or how to access them, or anything else that is relevant to the documentation
- If there is nothing to report, please just put "nothing to report" in a readme.md file, so that I know this file wasn't just forgotten
</script></section>
<section data-markdown id="readmemd"><script type="text/template">
## File formats
- Some things will be PDF (along with the source files in the repo):
- Definitely the user manual, technical report, an export of the final presentation
- Possibly the installation instructions and programming reference (those can be Markdown also)
- All other things will likely be Markdown
</script></section>
<section data-markdown><script type="text/template">
## Code base submission
- The assumption is that the `master` branch in the github repository contains the entire system that can be deployed on the customer's deployment host
- If there is ANYTHING that needs to be changed upon deployment, that should be indicated in the deployment plan
- For example: .htaccess files need changing, the database.php or database.yml needs updating, etc.
- You don't have to include their DB account information; just indicate that it needs updating
- Thus, you don't have to submit the code base to me (I have access to the git repo); but you will need to send it to the customer (see next slide)
</script></section>
<section data-markdown><script type="text/template">
## Code base submission
- A branch means that there is separate development ongoing
- As of the end of the semester, the assumption is that there is *no* ongoing development
- Thus, you should only have the `master` branch in the repo
- If you have a special case, please speak to me about it...
</script></section>
<section id="customer" data-markdown><script type="text/template">
## Hand-off to the customer, part 1
- You should e-mail the customer the following documents
- Include a one or two sentence explanation of what they are
- And CC me on that e-mail
- *Please convert Markdown to PDF when sending to the customer*
- You should only email the .pdf to your customer
- To email the customer:
- user-manual.md/pdf
- installation-instructions.md/pdf
- requirements-document.md/pdf
- programming-reference.md/pdf
- (continued next slide...)
</script></section>
<section data-markdown><script type="text/template">
## Hand-off to the customer, part 2
- More stuff to email the customer:
- A .zip file of the code base
- Indicate to them that I can also provide this code base as well
- You are welcome to download this from github, but be **SURE** to remove the .git/ directory before you re-zip it back up and email it to the customer!
- If the customer wants to see more of the documentation, that's fine
- Nothing is really secret from them; I just assumed they would not be interested in the rest
- And thank them for their participation! I want to remain on good terms!
</script></section>
<section data-markdown><script type="text/template">
## Github issues
- Upon completion of the project, the ONLY things that should be in the Github issues listing are bugs that you know are still there and are unresolved
- Meaning you should clear out all the issues!
- And if there are still bugs, please let me know so that we can chat about their status...
</script></section>
</section>
<section>
<section id="conclusion" data-markdown><script type="text/template">
# Conclusion
</script></section>
<section data-markdown><script type="text/template">
## I hate fluff
- What a waste!
- It's a waste of your time to write it
- It's a waste of my time to read it
- It's a waste of paper
- It's a waste of ink toner
- The only thing with a page requirement is the STS article, and with all the detailed sections described herein, you should not have a problem hitting that page length
- I will return any fluff-ridden pieces to you for you to dispose of (and rewrite)
</script></section>
<section data-markdown><script type="text/template">
## Due dates, part 1
- Due at the end of iterations 7-11:
- Iteration 7 (January 30th): deployment plan
- Iteration 8 (February 14th): installation instructions
- Iteration 9 (February 28th): master test plan
- Iteration 10 (March 13th): code coverage report
- Iteration 11 (March 27th): full transition plan, including the updated requirements document
- Due throughout the transition period (iterations 12-14; specific dates TBA): user manual, programming reference
- If you are really interested, you can find the due dates listed in the [iteration goals slide set](../uva/iteration-goals.html#/)
- Due ????: STS technical report
- I will need them two weeks before STS needs them
</script></section>
<section data-markdown><script type="text/template">
## Due dates, part 2
- Due at the end of iteration 14 (Tuesday, May 9th by noon): final presentation slide set and your tutorial
- Due at the end of iteration 14: the final hand-off to the customer, screen shot(s), and the one-slide version
- Note that I will have to check everything in the repo, so don't wait until the last minute to do them!
</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>