-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
375 lines (290 loc) · 18.8 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
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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Inspiring and empowering users and techies to become great writers</title>
<meta name="description" content="Inspiring and empowering users and techies to become great writers, and why that's important">
<meta name="author" content="Jo Cook, Astun Technology">
<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">
<link rel="stylesheet" href="css/reset.css">
<link rel="stylesheet" href="css/reveal.css">
<link rel="stylesheet" href="css/theme/black.css" id="theme">
<link rel="stylesheet" href="css/custom.css">
<!-- Theme used for syntax highlighting of code -->
<link rel="stylesheet" href="lib/css/monokai.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>
<!--[if lt IE 9]>
<script src="lib/js/html5shiv.js"></script>
<![endif]-->
</head>
<body>
<div class="reveal">
<!-- Any section element inside of this container is displayed as a slide -->
<div class="slides">
<section>
<h2>Inspiring and empowering users and techies to become great writers</h2>
<h3>and why that's important</h3>
<p>
<small>Presented by Jo Cook, Astun Technology | OSGeo | @archaeogeek</small>
</p>
</section>
<section>
<h3>Hi! I'm Jo *waves*</h3>
<h3 class="fragment">I'm not a developer</h3>
<h3 class="fragment"/>and I'm entirely new to #devrel</h3>
<h3 class="fragment"/>but I'm here to talk to you about a problem with open source projects</h3>
</section>
<section>
<h2>Step One: Acknowledge the Problem</h2>
</section>
<section>
<h3>Projects are dying!</h3>
<img src="./images/chart1.png" alt="piechart" height="300"/>
<blockquote>64% of the most active projects on GitHub rely on 1 or 2 developers to survive<footer>Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure</footer></blockquote>
<aside class="notes">Let's start from the premise that many vital projects are run by a very small team of developers, who often have day jobs and are doing this in their spare time</aside>
</section>
<section>
<h3>and they are not very diverse!</h3>
<img src="./images/chart2.png" alt="piechart" height="300"/>
<blockquote>The ratio of women in IT is about 17-25%... but in open source [it's] around 0.1-5%<footer>Sustainable Open Source, Jan Lehnhardt</footer></blockquote>
<aside class="notes">Obvs this is just one diversity metric but at the very least this means there's a pool of talent that can be mined for participation in projects</aside>
</section>
<section data-background-image="./images/barrier.jpg" alt="fence" class="full" data-background-size="cover" data-background-color="white">
<h3 style="color:black">Documentation is severely lacking!</h3>
<div class="box-left">
<blockquote>Lack of documentation is a highly effective barrier to participation... adoption and contribution
<footer>Riona MacNamara at Write the Docs Australia 2019 (via @knowledge_owl)</footer>
</blockquote>
</div>
<small class="attribution" style="color:black">image via <a href="http://www.peakpx.com">Peakpx</a>, CC0</small>
</section>
<section data-background-image="./images/facepalm.jpg" alt="bear" class="full" data-background-size="cover" data-background-color="white">
<h3 style="color:black">and you get people saying this:</h3>
<div class="box-right">
<blockquote style="color:white">My code is open source on GitHub, but I don't spend any effort making it easy for others to use it. If you want to figure it out yourself, have fun!<footer>Redacted to protect the innocent</footer></blockquote>
</div>
<aside class="notes">Having a wilfully bad onboarding process for your project is not a badge of honour</aside>
<small class="attribution" style="color:white">Bradley Howington, Pexels</small>
</section>
<section>
<h3>Yet getting help is tricky:</h3>
<img src="./images/chart3.png" alt="piechart" height="300"/>
<blockquote>Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents, yet 60% of contributors say they rarely or never contribute to documentation<footer>Github Open source survey 2017</footer></blockquote>
</section>
<section>
<h2>Step Two: Restate the problem</h2>
<h3 class="fragment">Open source projects are under-resourced, not well-documented, and don't attract diverse contributions</h3>
</section>
<section>
<h2>Step Three: Consider possible solutions</h2>
</section>
<section>
<h3>Find more resources</h3>
<blockquote>Long-term support is more about creating time than it is about money<footer>Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure</footer></blockquote>
<aside class="notes">Open source is not inherently flawed, but rather under-resourced (from same report)</aside>
</section>
<section>
<h3>Particularly for documentation</h3>
<blockquote>Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.<footer>Github Open Source Survey 2017 https://opensourcesurvey.org</footer></blockquote>
<aside class="notes">Expanding the pool of contributors and encouraging contributions to more than just code makes a project more resilient</aside>
</section>
<section>
<h2>=> Encouraging user contributions is really important</h2>
<h3 class="fragment">and here are some more reasons why...</h3>
<aside class="notes">Not the impolite, entitled, frequently rude ones</aside>
</section>
<section>
<h3>Developers might miss out steps</h3>
<img src="./images/draw_the_owl.png" alt="owl" height="300"/>
<blockquote>Step 2: Draw the rest of the *** owl<footer>Internet legend, 2008?</footer></blockquote>
<aside class="notes">It's easy for people close to the software at its most technical level to miss out steps in quick start guides and how-tos. At a workshop for a mapping library recently, I think 20% of the participants would have given up during the setup stage were it not for the assistants helping out</aside>
</section>
<section data-background-image="./images/confused.jpg" alt="pug" class="full" data-background-size="cover" data-background-color="white">
<div class="fragment boxed fade-left">
<h3 style="color:white">Developers are familiar with more technical terminologies</h3>
</div>
<div class="fragment boxed fade-left">
<blockquote>Just clone the dev branch, add the grunt tasks and recompile...<footer>Slightly made up example</footer></blockquote>
</div>
<aside class="notes">Developers may use overly technical language or phrasing. A Nielsen Norman Group survey concluded that only 5% of the population of 33 rich countries has high computer-related abilities and only a third can complete medium complexity tasks https://www.nngroup.com/articles/computer-skill-levels/</aside>
<small class="attribution" style="color:white">Pigsels, CC-0</small>
</section>
<section>
<h3>Users know what users expectations and needs are</h3>
<p>How are people actually using your project? Is it the way you expected them to?</p>
<aside class="notes">As projects become more successful they gain a life of their own. Users become more demanding, but also help to establish what's important, find novel use-cases, and what needs more documentation love</aside>
</section>
<section>
<h3>Users will actually want to use your documentation</h3>
<blockquote>The current state of ***'s software is the worst I've ever seen for any framework anywhere...I've repeatedly been reduced to searching through WWDC video transcripts to figure out where someone says something relevant to whatever I'm working on<footer>Slashdot, October 2019</footer></blockquote>
<aside class="notes">Are your docs fit for purpose? Are all the terms searchable (screenshots are bad for this), is it useable by people with different needs and abilities? PS it's not just about open source!</aside>
</section>
<section>
<h2>Step Four: Figure out what puts people off</h2>
</section>
<section data-background-image="./images/barrier.jpg" alt="barrier" class="full" data-background-size="cover" data-background-color="white">
<div class="fragment boxed fade-left">
<h2 style="color:white">High barriers to entry</h2>
</div>
<small class="attribution" style="color:white">Winsker, Pixabay</small>
</section>
<section>
<h3>A standard docs toolchain:</h3>
<p class="fragment bold">Install the correct versions of java, python, maven, sphinx, sphinx-bootstrap-theme</p>
<p class="fragment bold">Become a ReStructured Text ninja</p>
<p class="fragment bold">Understand about GitHub Forks, Pull Requests, Reviews, and Commits</p>
<p class="fragment bold">Then you can submit your first documentation change!</p>
<aside class="notes">It may be a learning curve for a contributor to learn how to submit a pull request, or learn reStructuredText syntax before they actually get to contribute, so ensure you provide instructions or links to guidance as well. Getting documentation and git toolchains set up on windows can be a nightmare even for technically proficient users</aside>
</section>
<section>
<h3>This applies to software in general these days</h3>
<blockquote>if you want to start building a full-stack web application in 2018, you may need to first install Node.js and the npm package manager, run a slew of npm commands to configure a custom toolchain with a CSS preprocessor and a JavaScript code bundler, adjust OS environment variables to detect all required library dependencies...<footer>Using Operating-System-Wide Activity Tracing, Alok Mysore and Philip J. Guo</footer></blockquote>
<aside class="notes">You're assuming people actually want to use your software as an end in it's own right, when it may just be a step towards achieving an entirely separate objective. Users will ensure your documentation gets people through these early painful setup stages</aside>
</section>
<section data-background-image="./images/nope.jpg" alt="nope" class="full" data-background-size="cover" data-background-color="white">
<h3 style="color:white">New contributors feel unwelcome</h3>
<div class="fragment boxed fade-left">
<blockquote style="color:white">Negative experiences have real consequences for project health. 21% of people who experienced or witnessed a negative behavior said they stopped contributing to a project because of it<footer>Github Open Source Survey 2017</footer></blockquote>
</div>
<aside class="notes">Contributors are not an annoyance, or an increased burden, or suitable only for minor tasks https://opensource.com/business/16/6/bad-practice-foss-projects-management</aside>
<small class="attribution" style="color:white">Tom Hilton, Flickr, CC-By-2.0</small>
</section>
<section>
<h2>Step Five: Figure out a better solution</h2>
</section>
<section data-background-image="./images/reducebarrier.jpg" alt="jump" class="full" data-background-size="cover" data-background-color="white">
<div class="fragment boxed fade-left">
<h2 style="color:white">Reduce barriers to entry</h2>
</div>
<p class="fragment boxed fade-left" style="color:white">Allow easy ways for users to contribute</p>
<p class="fragment boxed fade-left" style="color:white">(Preferrably so they don't need to install additinal software)</p>
<p class="fragment boxed fade-left" style="color:white">Get their contributions live as quickly as possible</p>
<p class="fragment boxed fade-left" style="color:white">Acknowledge and encourage contributions, no matter how small</p>
<aside class="notes">Reduce the friction for a user to quickly fix a mistake they've spotted, or otherwise contribute. This is better than sending someone to a page for submitting an issue (which is what MDN and PostgreSQL both do). Label low-hanging fruit or good first issues</aside>
<small class="attribution" style="color:black">hansbenn, pixabay.com</small>
</section>
<section data-background-image="./images/thankyou.jpg" alt="thanks" class="full" data-background-size="cover" data-background-color="white">
<div class="fragment boxed fade-left" style="margin-top:150px !important;">
<h3 style="color:white">Attract and nurture existing technical writers</h3>
</div>
<blockquote style="color:white" class="fragment boxed fade-left">It is no trivial task to make complex information in the technical domain simple for users to understand and follow<footer>https://idratherbewriting.com/2018/11/19/avoid-being-secretary-for-engineers/</footer></blockquote>
<aside class="notes">Technical Writers != Secretaries, they have subject matter expertise</aside>
<small class="attribution" style="color:white">Pintrest, yuck</small>
</section>
<section data-background-image="./images/templateallthethings.jpeg" alt="template" class="full" data-background-size="contain" data-background-color="white">
<p style="color:white; margin-top:150px !important" class="fragment boxed fade-left">Provide workflows that make it easier to write good documentation</p>
<p style="color:white" class="fragment boxed fade-left">Follow, learn from, and contribute to existing good practices</p>
</section>
<section>
<h2>So, to summarise, this is important because...</h2>
</section>
<section data-state='sparkley'>
<h3>Encouraging help with documentation for your project <bold class="fragment sparkley">encourages empathy</bold>, and <bold class="fragment sparkley">improves diversity</bold></h3>
</section>
<section data-background-image="./images/juggling.jpg" alt="bear" class="full" data-background-size="cover" data-background-color="white">
<h3 style="color:white; margin:100px !important">But I don't have time!!!1!11!</h3>
<small class="attribution" style="color:white">Michael Jastremski, openphoto.net</small>
</section>
<section data-background-image="./images/seasonofdocs.png" alt="GSoD" class="full" data-background-size="cover" data-background-color="white">
<div class="boxed">
<h3 style="color:white; margin-top:300px !important">Enter Google Season of Docs</h3>
<p>Matching technical writers with open source projects</p>
<p>For 3 or 6 months</p>
</div>
<aside class="notes">For OSGeo- OSGeoLive Quick Starts and GeoNetwork</aside>
</section>
<section data-background-image="./images/question.jpg" alt="question" class="full" data-background-size="cover" data-background-color="white">
<h3 style="color:black">So we thought...why not abstract that expertise and work to make something more generic?</h3>
<small class="attribution" style="color:black">Skeptical Cat, Flickr, CC-By-2.0</small>
</section>
<section>
<h2>Step Six: Building an actual solution</h2>
</section>
<section data-background-image="./images/doctopus-with-docs.png" alt="tGDP" class="full" data-background-size="cover" data-background-color="white" data-state='sparkley'>
<h2 class="fragment alsosparkley" style="visibility:visible">The Good Docs Project</h2>
</section>
<section>
<h3>Aim #1: Identify all the elements of good documentation that a project needs</h3>
<p>and provide best-practice resources and templates for each of them</p>
<aside class="notes">Tutorials, how-tos, reference, technical documentation</aside>
</section>
<section>
<h3>Aim #2: An Open Source Minimal Viable Docset</h3>
<p>Helping you to create a baseline set of docs for all stages of a project from initiation through to maturity</p>
</section>
<section>
<h3>Aim #3: A community of writers, users and techies</h3>
<p>Practical tips, advice, help for all parts of the process</p>
</section>
<section data-state="sparkley">
<h3>Increasing <bold class="fragment sparkley">quality and consistency</bold>, <bold class="fragment sparkley">saving time for developers</bold>, <bold class="fragment sparkley">democratising knowledge</bold>, and generally<bold class="fragment sparkley">making the world a better place</bold></h3>
</section>
<section>
<h3>Join us at thegooddocsproject.dev | @thegooddocs | thegooddocs.slack.com | thegooddocsproject.groups.io</h3>
</section>
<section>
<h3>Thank You!</h3>
<p>w: archaeogeek.github.io/devrelcon2019 | t: @archaeogeek</p>
</section>
</div>
</div>
<script src="js/reveal.js"></script>
<script src="js/jquery-3.4.1.slim.min.js"></script>
<script src="js/jquery-canvas-sparkles.js"></script>
<script>
// More info https://github.com/hakimel/reveal.js#configuration
Reveal.initialize({
controls: true,
progress: true,
center: true,
hash: true,
showNotes: "separate-page",
pdfSeparateFragments: false,
pdfMaxPagesPerSlide: 1,
transition: 'slide', // none/fade/slide/convex/concave/zoom
// More info https://github.com/hakimel/reveal.js#dependencies
dependencies: [
{ src: 'plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'plugin/highlight/highlight.js', async: true },
{ src: 'plugin/search/search.js', async: true },
{ src: 'plugin/zoom-js/zoom.js', async: true },
{ src: 'plugin/notes/notes.js', async: true }
]
});
Reveal.addEventListener('sparkley', function() {
Reveal.addEventListener( 'fragmentshown', function( event ) {
// event.fragment = the fragment DOM element
var timer;
clearTimeout(timer);
$curfrag = $(event.fragment);
$curfrag.sparkle({"color": "rainbow" ,
"minSize": 10 ,
"maxSize": 20 ,
"overlap": 0 ,
"direction": "both" ,
"speed": 1,
"fadeSpeed":1000});
$curfrag.off("mouseover.sparkle")
$curfrag.trigger("start.sparkle")
.on("click");
timer = setTimeout(function(){
$curfrag.trigger("stop.sparkle");
},300);
} );
Reveal.addEventListener( 'fragmenthidden', function( event ) {
$curfrag.trigger("stop.sparkle")
});
}, false );
</script>
</body>
</html>