Skip to content

Latest commit

 

History

History
250 lines (181 loc) · 5.5 KB

hackathon-help-system.adoc

File metadata and controls

250 lines (181 loc) · 5.5 KB
Raw

From Hackathon to Help System

The Original Idea

background

  • Field help and long form docs.

  • Provisioned using Open Source tooling.

  • Written in AsciiDoc.

  • Mapped to pages and fields with .yml or .json.

  • Live rendered using asciidoctor.js on demand.

An Opportunity

background

  • Ladbrokes Hackathon.

  • Volunteered from a docs perspective.

  • Was offered an opportunity to submit my own hack!

The Challenge

background

  • URL slugs not implemented for page element atomicity.

  • Fields not uniquely or consistently identified.

The Hackathon Solution

background

  • DragonForce an embedded help solution inside Manage.

  • Display rendered help content in a new tab when you click a Help Button.

  • You have two days.

MVP

background

  • Give users access to docs inside the product.

  • Do it using open source technology.

  • Make the content single source.

  • Make everything automatic.

  • Separate docs releases from code releases.

Technology

background

URL Matching

background

  • Help pages named the same as the PHP page to document.

  • index.php > index.adoc > index.html.

  • Javascript button loaded files from a pre-set location in webroot.

Watcher script

background
update-newadmin-docs.sh
#!/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

  • Resides in the tools directory of the app webroot.

  • Watches for changes per the sleep interval.

  • Sync html changes from Git to /var/www/docs.

The Judging

help demo
Note

  1. Click Help

  2. Page loads

  3. TOC

  4. Page navigation

  5. Whoops!

Hackathon Quality

  • Not an engineering issue.

  • Links a bit fragile.

  • Totally my fault. :(

Concept Was a Winner!

Through the fire and the flames we carry on!
— Dragonforce
background

  • One of three winners chosen by the CTO.

  • $250 Prize.

  • HUGE boost in confidence!

What Now?

So we’ve made this proof of concept.

background

The Big Question

Can we get this solution released?

The Answer

We Can Do It

Make It So

background

Process

background

  • Documented hack in README.adoc to capture baseline state.

  • Made an Epic with Stories and Tasks.

  • Employed Tech Writing skills to make solid Stories and Project Docs.

People

background

  • Worked with Hackathon engineer to hand over knowledge to dev team.

  • Worked iteratively with developers to "get it right".

Engineering

background

  • Used Deploy Keys instead of self-signed RSA.

  • Decreased sync task to once-a-day.

  • Help Button improved to visually show presence of help files.

Ship It

background

  • Dev approved.

  • QA approved.

  • Released into the wild.

Hindsight

  • Things work OK.

  • Things have to change for my sanity.

Limitations

background

  • URL matching requires the exact filename.

  • Can’t use a nested file tree to group common files.

  • Changing destination html file requires changes to Help Button Javascript.

  • Missing help files cause Javascript browser errors in Developer environments.

  • Changing anything except content requires a code release and testing.

The Future

background

  • Realise the Hawkular dream of config driven docs.

  • Change tooling without impacting Help Button functionality.

  • Use NPM-based tooling to improve reliability.

  • Use GitLab Runners to better automate builds.

  • Set aside one day a week to write Embedded Help.

Take-aways

background

  • That developers are your allies and actually care about docs.

  • That DevOps get stuff done, and are worth having lunch with.

  • That being outside your comfort zone can sometimes be comfortable.

  • That you can be an entrepreneur inside your department.