-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
310 lines (273 loc) · 13.2 KB
/
index.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
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
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>reveal.js</title>
<link rel="stylesheet" href="css/reveal.css">
<link rel="stylesheet" href="css/theme/white.css">
<!-- Theme used for syntax highlighting of code -->
<link rel="stylesheet" href="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 ) ? 'css/print/pdf.css' : 'css/print/paper.css';
document.getElementsByTagName( 'head' )[0].appendChild( link );
</script>
</head>
<body>
<div class="reveal">
<div class="slides">
<section>
<h1>Session 2: Technical Writing and GitHub</h1>
<h2>DigiPres101: Programming Basics and Preservation Tools </br> AMIA Conference 2016</h2>
<small>Erwin Verbruggen </br> <a href="http://beeldengeluid.nl/en">Netherlands Institute for Sound and Vision</a></small>
</section>
<section>
<h1>Agenda</h1>
<ol>
<li>Technical Writing</li>
<li>GitHub</li>
</ul>
</ol>
</section>
<section>
<section>
<h1>1. Technical Writing</h1>
<ol>
<li>communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations;</li>
<li>communicating through technology, such as web pages, help files, or social media sites;</li>
<li>providing instructions about how to do something, regardless of the task's technical nature</li>
</ol>
<pre>Source: <a href="http://www.stc.org/about-stc/the-profession-all-about-technical-communication/defining-tc">Society for Technical Communication</a></pre>
<aside class="notes">You've just been given an introduction to the command line. We will now (mostly) revert to the domain of human-understandable language</aside>
</section>
<section>
<h2>Why bother?</h2>
<ol>
<p class="fragment">Move your project/work forward</p>
<p class="fragment">Interact with your techie colleagues</p>
<p class="fragment">Participate in hackathons (tomorrow? <strong>#AVHackDay</strong>)</p>
<p class="fragment">Support <a href="https://github.com/amiaopensource/">open source projects</a></p>
</ol>
</section>
<section><h2>Things Developers Do (1/2)</h2>
<ul>
<p class="fragment">Discuss <strong>interface design</strong> with designers</p>
<ul>
<p class="fragment">Test a site on various browsers / devices</p>
<p class="fragment">Tweak the design when it doesn’t work on the browser/device</p>
</ul>
<p class="fragment">Write <strong>bug reports</strong></p>
<ul>
<p class="fragment">Reproduce bugs and confirm with the bug reporter that’s the problem</p>
<p class="fragment">Communicate about <strong>feature requests</strong> and bugs</p>
</ul>
</ul>
<pre>Source: <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a></pre>
<aside class="notes">How can you, as a non-programmer help a coder? Coders actually don’t code that much. ‘Real’ coding, like typing code on a keyboard in a text editor, takes only between 2 to 3 hours during an average 8-hour workday. Things a typical web developer might do:
</aside>
</section>
<section><h3>Things Developers Do (2/2)</h3>
<ul>
<p class="fragment">Google for error messages and how to fix specific bugs</p>
<p class="fragment">Add test data to a CMS to check if it works</p>
<p class="fragment">Clean up an Excel or CSV dump with data, or import it in a database</p>
<p class="fragment">Sketch out possible solutions for a <strong>user story</strong></p>
<p class="fragment">Decide which task is most important</p>
<p class="fragment">Write blog posts, send tweets, make screenshots of the product</p>
</ul>
<pre>Source: <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a></pre>
<aside class="notes">
=> None of these require writing a single line of code
</aside>
</section>
<section>
<blockquote cite="http://ablwr.github.io/blog/2016/09/23/facing-fear-first/">
All archivists are digital archivists.<br>
- Ashley Blewer
</blockquote>
</section>
<section><h2>Things Non-Coders Can Do (1/3)</h2>
<ul>
<p class="fragment">Flesh out user stories to exhaustively <br><strong>detail a specific function or workflow</strong> of the project</p>
<p class="fragment">Create and/or tweak the <strong>interface design</strong><br> (simple paper prototyping or Photoshop/Illustrator)</p>
<p class="fragment">Test the product in <strong>all possible combinations</strong> of OS/browser - and write bug reports.</p>
<p class="fragment">Clean available data and export it to exchangeable formats (e.g. CSV).</p>
</ul>
<pre>Source: <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a></pre>
</section>
<section><h3>Things Non-coders Can Do (2/3)</h3>
<ul>
<p class="fragment">Write / blog / tweet about the project</p>
<ul>
<p class="fragment">Create a video / graphic / presentation about the project</p>
<p class="fragment">Set up a blog / site / Facebook page showcasing the project</p>
</ul>
<p class="fragment">Fast and simple <strong>user testing</strong></p>
<p class="fragment">Necessary paperwork - including <strong>documentation</strong></p>
</ul>
<pre>Source: <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a></pre>
</section>
<section><h3>Things Non-coders Can Do (3/3)</h3>
<ul>
<p class="fragment">Track usage of the project using an analytics package</p>
<p class="fragment">Communicate with clients / users / designers</p>
<p class="fragment">Fill the database / CMS with ‘real’ content</p>
<p class="fragment">Research hosting / catering / workspace</p>
<p class="fragment">Set up servers, hosting and deployment procedures (command line)</p>
<p class="fragment">Prioritisation and task assignment</p>
</ul>
<pre>Source: <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a></pre>
</section>
<section><h3>Requirements (1)</h3>
<h4>Eliciting Requirements</h4>
<ul>
<p class="fragment">Interviews</p>
<p class="fragment">Focus Groups</p>
<p class="fragment">Requirement Workshops</p>
<p class="fragment">Surveys/Questionnaires</p>
<p class="fragment">Document Analysis</p>
<p class="fragment">Brainstorming</p>
<p class="fragment">Observation</p>
</ul>
</section>
<section data-markdown>
<script type="text/template">
### Requirements (2)
#### User Stories
As a... | I want ... | So that...
--|--|--
User | built-in help pages | assistance is available offline
Admin | restricted access per user level | user management is organised
... | ... | ...
<aside class="notes">
User stories are used with agile software development methodologies as the basis for defining the functions a business system must provide, and to facilitate requirements management. It captures the "who", "what" and "why" of a requirement in a simple, concise way, often limited in detail by what can be hand-written on a small paper notecard.
</aside>
</script>
</section>
<section><h3>Requirements (3)</h3>
<h4>Requirements in Open Source</h4>
The Power of the Mailing List
<img data-src="img/ffmpegnewsletter.png" alt="ffmpeg">
</section>
<section><h3>Documentation</h3>
<img width="50%" height="50%" data-src="img/documentation.jpg" alt="documentation">
<aside class="notes">One of the biggest sore spots for most open source software (and even proprietary software) is a lack of clear, concise documentation</aside>
</section>
<section><h3>Feedback</h3>
<ul>
<p class="fragment">Try to make the problem specific but concise</p>
<p class="fragment">Explain exactly what you were doing to cause the error to occur</p>
<p class="fragment">Make sure to mention if you are able to make the bug repeat, or if it only happened once and not again</p>
<p class="fragment">Assign to person (if you know who should fix)</p>
<p class="fragment">Be brave, kind, assertive</p>
<pre>Source: <a href="http://ablwr.github.io/blog/2014/11/04/non-technical-persons-guide-to-becoming-an-open-source-software-contributor-via-github/">Non-Technical Person’s Guide to <br>Becoming an Open Source Software Contributor Via Github</a></pre>
</ul>
</section>
<section><h3>Feedback</h3>
<h3>Bug trackers I've (learned to) love</h3>
<img data-src="img/mantis.png" alt="Mantis">
</section>
<section><h3>Feedback</h3>
<h3>Bug trackers I've (learned to) love</h3>
<img data-src="img/awesome-broadcasting.png" alt="Mantis">
</section>
</section>
<section>
<section>
<h1>2. GitHub</h1>
a distributed revision control system
<aside class="notes">
<p>there are apps for using Git like GitHub for Mac and Windows, or Tower; <br>
dozens of different text editors; <br>
and competitors to GitHub like Bitbucket, Google Code, or SourceForge</p></aside>
</section>
<section>
<h1>Version control</h1>
the <em>diff</em>
<!-- example: Wikipedia diff & commit -->
<aside class="notes">
"don’t worry about fucking things up. It’s git: a distributed revision control system. Its entire purpose for existing is to protect against things getting fucked up"</aside>
</section>
<section>
<h1>Parlance</h1>
DigiPres folks take note:
A <em>repository</em> is not a <em>repository</em>
<ul>
<li><em>branching</em></li>
<li><em>merging</em></li>
<ul>
</section>
<section>
<h2>Using GitHub for Documentation</h2>
Adding & improving / Request to Change Things
<ul>
<p class="fragment">Make change => Commit changes</p>
<p class="fragment">Fork => Changes on your account only</p>
<p class="fragment">Pull request => Ask for changes in main codebase</p>
<p class="fragment">Peer review => Comments</p>
</ul>
</section>
<section>
Example: Testing on Ashley Blewer's GitHub <br> <a href="https://github.com/ablwr/testing">https://github.com/ablwr/testing</a>
</section>
<section>
<h2>Feedback, feature request, bugs</h2>
<h3>Issues</h3>
If there’s something bigger you want to fix but you don’t know how to do it, you can open an issue.
<ul>
<li>the best way to fix a problem is by <em>doing it yourself</em></li>
<li>provide feedback and bring up problems</li>
</ul>
</section>
<section>
<h2>Formatting: Markdown</h2>
</section>
<section data-background-video-muted="https://youtu.be/l2rLqkx7WTE?t=20ms">
<h2>Interface vs Command Line</h2>
</section>
<section>
<img width="50%" height="50%" data-src="img/git_cheat_sheet.png" alt="git_cheat_sheet">
</section>
</section>
<section>
<h1>Check out at #AMIA16</h1>
<ul>
<li>Meeting: Open Source Committee<br>Thurs, Nov. 10, 12:00 PM @Carneigie III - Conference Level</a>.</li>
<li>AMIA <a href="https://github.com/amiaopensource/">Open Source GitHub</a></li>
</ul>
</section>
<section>
<h1>Helpful Resources</h1>
<ul>
<li>Ashley Blewer (2014), <a href="http://ablwr.github.io/blog/2014/11/04/non-technical-persons-guide-to-becoming-an-open-source-software-contributor-via-github/">Non-Technical Person’s Guide to Becoming an Open Source Software Contributor Via Github</a>.</li>
<li>Lauren Sorensen (2014), <a href="https://youtu.be/l2rLqkx7WTE?t=20ms">Open Source and Digital Preservation and Access: Open Source Tools, Technologies and Considerations</a>. Presented at the 2014 AMIA Open Source Digital Preservation & Access Stream.</li>
<li>Hay Kranen (2015), <a href="https://www.haykranen.nl/2015/05/11/help-a-coder-even-if-you-cant-code/">Help a Coder, Even If You Can’t Code</a>.</li>
</ul>
</section>
</section>
</div>
</div>
<script src="lib/js/head.min.js"></script>
<script src="js/reveal.js"></script>
<script>
// More info https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({
history: true,
slidenumber: true,
progress: true,
showNotes: false,
// More info https://github.com/hakimel/reveal.js#dependencies
dependencies: [
{ src: 'plugin/markdown/marked.js' },
{ src: 'plugin/markdown/markdown.js' },
{ src: 'plugin/notes/notes.js', async: true },
{ src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } }
]
});
</script>
</body>
</html>