-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathhackathon-help-system.html
More file actions
114 lines (108 loc) · 13.6 KB
/
hackathon-help-system.html
File metadata and controls
114 lines (108 loc) · 13.6 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
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="author" content="Jared Morgan"><title>From Hackathon to Help System</title><meta content="yes" name="apple-mobile-web-app-capable"><meta content="black-translucent" name="apple-mobile-web-app-status-bar-style"><meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui" name="viewport"><link href="reveal.js/css/reveal.css" rel="stylesheet"><link rel="stylesheet" href="reveal.js/css/theme/league.css" id="theme"><link href="reveal.js/lib/css/zenburn.css" rel="stylesheet"><script>document.write( '<link rel="stylesheet" href="reveal.js/css/print/' + ( window.location.search.match( /print-pdf/gi ) ? 'pdf' : 'paper' ) + '.css" type="text/css" media="print">' );</script></head><body><div class="reveal"><div class="slides"><section class="title"><h1>From Hackathon to Help System</h1><p class="author"><small>Jared Morgan</small></p></section><section id="original_idea" data-background-image="images/hawkular_mvp.jpg" data-background-size="contain"><h2>The Original Idea</h2>
<div class="ulist step"><ul><li class="fragment"><p>Field help and long form docs.</p></li><li class="fragment"><p>Provisioned using Open Source tooling.</p></li><li class="fragment"><p>Written in AsciiDoc.</p></li><li class="fragment"><p>Mapped to pages and fields with <code>.yml</code> or <code>.json</code>.</p></li><li class="fragment"><p>Live rendered using <code>asciidoctor.js</code> on demand.</p></li></ul></div></section>
<section id="_an_opportunity" data-background-image="images/opportunity.jpg" data-background-size="contain"><h2>An Opportunity</h2>
<div class="ulist step"><ul><li class="fragment"><p>Ladbrokes Hackathon.</p></li><li class="fragment"><p>Volunteered from a docs perspective.</p></li><li class="fragment"><p>Was offered an opportunity to submit my own hack!</p></li></ul></div></section>
<section id="challenge" data-background-image="images/challenge.png" data-background-size="contain">
<div class="ulist step"><ul><li class="fragment"><p>URL slugs not implemented for page element atomicity.</p></li><li class="fragment"><p>Fields not uniquely or consistently identified.</p></li></ul></div></section>
<section><section id="hackathon" data-background-image="images/goal-clipart.svg" data-background-size="contain"><h2>The Hackathon Solution</h2><div class="ulist step"><ul><li class="fragment"><p><em>DragonForce</em> an embedded help solution inside Manage.</p></li><li class="fragment"><p>Display rendered help content in a new tab when you click a Help Button.</p></li><li class="fragment"><p>You have two days.</p></li></ul></div></section><section id="mvp" data-background-image="images/goal-clipart.svg" data-background-size="contain"><h2>MVP</h2>
<div class="ulist step"><ul><li class="fragment"><p>Give users access to docs inside the product.</p></li><li class="fragment"><p>Do it using open source technology.</p></li><li class="fragment"><p>Make the content single source.</p></li><li class="fragment"><p>Make everything automatic.</p></li><li class="fragment"><p>Separate docs releases from code releases.</p></li></ul></div></section><section id="technology" data-background-image="images/goal-clipart.svg" data-background-size="contain"><h2>Technology</h2>
<div class="ulist"><ul><li><p><a href="http://asciidoctor.org/docs/">Asciidoctor</a> source content.</p></li><li><p><a href="https://middlemanapp.com/">Middleman</a> Static Site Builder.</p></li><li><p><a href="https://github.com/bryanbraun/franklin">Franklin</a> Static Site Framework.</p></li><li><p>GitLab on-premise hosted.</p></li></ul></div></section><section id="url_matching" data-background-image="images/goal-clipart.svg" data-background-size="contain"><h2>URL Matching</h2>
<div class="ulist"><ul><li><p>Help pages named the same as the PHP page to document.</p></li><li><p><code>index.php > index.adoc > index.html</code>.</p></li><li><p>Javascript button loaded files from a pre-set location in webroot.</p></li></ul></div></section><section id="watcher" data-background-image="images/goal-clipart.svg" data-background-size="contain"><h2>Watcher script</h2>
<div class="listingblock"><div class="title"><code>update-newadmin-docs.sh</code></div><div class="content"><pre class="highlight"><code class="bash language-bash">#!/bin/bash
if [ ! -d /docs/ ]; then
git clone ssh://git@gitlab:12345/docs/embedded-docs.git /docs/
fi
cd /docs/ && \
git pull && \
git reset --hard HEAD && \
rsync --delete-after -a /docs/build/ /var/www/docs/
sleep 300</code></pre></div></div>
<div class="ulist"><ul><li><p>Resides in the tools directory of the app webroot.</p></li><li><p>Watches for changes per the <code>sleep</code> interval.</p></li><li><p>Sync html changes from Git to <code>/var/www/docs</code>.</p></li></ul></div></section></section>
<section><section id="judging"><h2>The Judging</h2><div class="imageblock" style=""><img src="images/help_demo.gif" alt="help demo"></div><aside class="notes"><div class="olist arabic"><ol class="arabic"><li><p>Click <b class="button">Help</b></p></li><li><p>Page loads</p></li><li><p>TOC</p></li><li><p>Page navigation</p></li><li><p>Whoops!</p></li></ol></div></aside></section><section id="quality"><h2>Hackathon Quality</h2><div class="ulist"><ul><li><p>Not an engineering issue.</p></li><li><p>Links a bit fragile.</p></li><li><p>Totally my fault. :(</p></li></ul></div></section><section id="winner" data-background-image="images/we_carry_on.gif" data-background-size="contain"><div class="quoteblock"><blockquote>Through the fire and the flames we carry on!</blockquote><div class="attribution">— Dragonforce</div></div>
<div class="ulist step"><ul><li class="fragment"><p>One of three winners chosen by the CTO.</p></li><li class="fragment"><p>$250 Prize.</p></li><li class="fragment"><p>HUGE boost in confidence!</p></li></ul></div></section></section>
<section><section id="what_now" data-background-image="images/Blueprint_of_Victory.jpg" data-background-size="cover"><h2>What Now?</h2><div class="paragraph"><p>So we’ve made this proof of concept.</p></div></section><section id="big_question"><h2>The Big Question</h2><div class="paragraph"><p>Can we get this solution released?</p></div></section><section id="answer"><h2>The Answer</h2><div class="imageblock" style=""><img src="images/We_Can_Do_It.jpg" alt="We Can Do It" width="400px"></div></section></section>
<section><section id="productise" data-background-image="images/productise_picard.jpg" data-background-size="contain"></section><section id="process" data-background-image="images/productise_picard.jpg" data-background-size="contain"><h2>Process</h2>
<div class="ulist"><ul><li><p>Documented hack in <code>README.adoc</code> to capture baseline state.</p></li><li><p>Made an Epic with Stories and Tasks.</p></li><li><p>Employed Tech Writing skills to make solid Stories and Project Docs.</p></li></ul></div></section><section id="people" data-background-image="images/productise_picard.jpg" data-background-size="contain"><h2>People</h2>
<div class="ulist"><ul><li><p>Worked with Hackathon engineer to hand over knowledge to dev team.</p></li><li><p>Worked iteratively with developers to "get it right".</p></li></ul></div></section><section id="engineering" data-background-image="images/productise_picard.jpg" data-background-size="contain"><h2>Engineering</h2>
<div class="ulist"><ul><li><p>Used Deploy Keys instead of self-signed RSA.</p></li><li><p>Decreased sync task to once-a-day.</p></li><li><p>Help Button improved to visually show presence of help files.</p></li></ul></div></section></section>
<section id="_ship_it" data-background-image="images/ship.gif" data-background-size="contain">
<div class="ulist step"><ul><li class="fragment"><p>Dev approved.</p></li><li class="fragment"><p>QA approved.</p></li><li class="fragment"><p>Released into the wild.</p></li></ul></div></section>
<section><section id="lessons"><h2>Hindsight</h2><div class="ulist step"><ul><li class="fragment"><p>Things work OK.</p></li><li class="fragment"><p>Things have to change for my sanity.</p></li></ul></div></section><section id="limitations" data-background-image="images/present.jpg" data-background-size="contain"><h2>Limitations</h2>
<div class="ulist step"><ul><li class="fragment"><p>URL matching requires the exact filename.</p></li><li class="fragment"><p>Can’t use a nested file tree to group common files.</p></li><li class="fragment"><p>Changing destination html file requires changes to Help Button Javascript.</p></li><li class="fragment"><p>Missing help files cause Javascript browser errors in Developer environments.</p></li><li class="fragment"><p>Changing anything <strong>except</strong> content requires a code release and testing.</p></li></ul></div></section><section id="future" data-background-image="images/future.jpg" data-background-size="contain"><h2>The Future</h2>
<div class="ulist step"><ul><li class="fragment"><p>Realise the Hawkular dream of config driven docs.</p></li><li class="fragment"><p>Change tooling without impacting Help Button functionality.</p></li><li class="fragment"><p>Use NPM-based tooling to improve reliability.</p></li><li class="fragment"><p>Use GitLab Runners to better automate builds.</p></li><li class="fragment"><p>Set aside one day a week to write Embedded Help.</p></li></ul></div></section></section>
<section id="takeaways" data-background-image="images/coffee.svg" data-background-size="contain"><h2>Take-aways</h2>
<div class="ulist step"><ul><li class="fragment"><p>That developers are your allies and actually care about docs.</p></li><li class="fragment"><p>That DevOps get stuff done, and are worth having lunch with.</p></li><li class="fragment"><p>That being outside your comfort zone can sometimes be comfortable.</p></li><li class="fragment"><p>That you can be an entrepreneur inside your department.</p></li></ul></div></section>
<section id="_questions" data-background-image="images/jared_metal.jpg" data-background-size="contain">
<div class="ulist"><ul><li><p><a href="mailto:jaredleonmorgan@gmail.com">jaredleonmorgan@gmail.com</a></p></li><li><p><a href="https://twitter.com/jaredmorgs">@jaredmorgs</a></p></li><li><p><a href="https://writethedocs.slack.com" class="bare">https://writethedocs.slack.com</a> #general room.</p></li></ul></div></section></div></div><script src="reveal.js/lib/js/head.min.js"></script><script src="reveal.js/js/reveal.js"></script><script>// See https://github.com/hakimel/reveal.js#configuration for a full list of configuration options
Reveal.initialize({
// Display controls in the bottom right corner
controls: true,
// Display a presentation progress bar
progress: true,
// Display the page number of the current slide
slideNumber: true,
// Push each slide change to the browser history
history: false,
// Enable keyboard shortcuts for navigation
keyboard: true,
// Enable the slide overview mode
overview: true,
// Vertical centering of slides
center: true,
// Enables touch navigation on devices with touch input
touch: true,
// Loop the presentation
loop: false,
// Change the presentation direction to be RTL
rtl: false,
// Turns fragments on and off globally
fragments: true,
// Flags if the presentation is running in an embedded mode,
// i.e. contained within a limited portion of the screen
embedded: false,
// Number of milliseconds between automatically proceeding to the
// next slide, disabled when set to 0, this value can be overwritten
// by using a data-autoslide attribute on your slides
autoSlide: 0,
// Stop auto-sliding after user input
autoSlideStoppable: true,
// Enable slide navigation via mouse wheel
mouseWheel: false,
// Hides the address bar on mobile devices
hideAddressBar: true,
// Opens links in an iframe preview overlay
previewLinks: false,
// Theme (e.g., beige, black, league, night, serif, simple, sky, solarized, white)
// NOTE setting the theme in the config no longer works in reveal.js 3.x
//theme: Reveal.getQueryHash().theme || 'league',
// Transition style (e.g., none, fade, slide, convex, concave, zoom)
transition: Reveal.getQueryHash().transition || 'concave',
// Transition speed (e.g., default, fast, slow)
transitionSpeed: 'default',
// Transition style for full page slide backgrounds (e.g., none, fade, slide, convex, concave, zoom)
backgroundTransition: 'fade',
// Number of slides away from the current that are visible
viewDistance: 3,
// Parallax background image (e.g., "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'")
parallaxBackgroundImage: '',
// Parallax background size in CSS syntax (e.g., "2100px 900px")
parallaxBackgroundSize: '',
// The "normal" size of the presentation, aspect ratio will be preserved
// when the presentation is scaled to fit different resolutions. Can be
// specified using percentage units.
width: 960,
height: 700,
// Factor of the display size that should remain empty around the content
margin: 0.1,
// Bounds for smallest/largest possible scale to apply to content
minScale: 0.2,
maxScale: 1.5,
// Optional libraries used to extend on reveal.js
dependencies: [
{ src: 'reveal.js/lib/js/classList.js', condition: function() { return !document.body.classList; } },
{ src: 'reveal.js/plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'reveal.js/plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
{ src: 'reveal.js/plugin/zoom-js/zoom.js', async: true, condition: function() { return !!document.body.classList; } },
{ src: 'reveal.js/plugin/notes/notes.js', async: true, condition: function() { return !!document.body.classList; } }
]
});</script></body></html>