We’re back to using Slack for product development communication again, so I’ve been keen to tie in the documentation updates I do via Dexy & Asciidoctor to Slack. What I wanted was to notify the channels setup per product of a new version of the specification along with the URL to the documentation site.
Gitlab has Slack integration ‘out of the box’ as described here. Here’s what that looks like:
GitLab [10:30 PM]
James Gallagher pushed to branch master of etckeeper/gitlab (Compare changes)
629601425: saving uncommitted changes in /etc prior to apt run – James Gallagher
ea40dff39: committing changes in /etc after apt run
-adduser 3.113ubuntu2 Show more…
This works great where the audience for the notification are interested in code/configuration changes but doesn’t fit with the use case I described above. So that meant looking instead at a specific Gitlab use case: Web Hooks for tag push events. As I mentioned in the Dexy & Asciidoctor post I tag new versions of specifications – hence tying the notification to ‘tag push events’.
The rest of this post describes the high level approach I took and the [awful] code I used.
In the post Dexy & Asciidoc(tor): A Business Analyst’s documentation tool to look at I went through how I’m using the two tools at the moment. I promised to provide an example within a few days but this has turned into a month now. Anyway, attached this post are the HTML (image not included, you’ll need the ZIP) and PDF outputs along with the full Dexy ‘project’. The content is in a Gitlab git repository.
Like many a BA, I get cranky with Microsoft Word as a tool for writing requirements specification documents. ‘Track Changes’ functionality isn’t version control and very quickly becomes unwieldy. I also find that document formatting behaves inconsistently when you get into different sets of section formatting, even when you try to bend numbered lists to your will. I’ve also used IBM’s Rational DOORS in the past for documenting requirements and you get used to that idea of structured editing and establishing relationships between requirements. So, I decided one evening that I’d go to good old plain text and use a markup language for formatting so that I could have absolute control over my documentation.
which led to
Off I went with "What is dexy?" and the bit that stood out for me was:
Dexy makes it easier to create technical documents by doing the repetitive parts for you. Dexy provides a consistent interface to tools and scripts so you don’t have to run them manually. Your project’s dexy configuration keeps track of what to run, in which order, and with what parameters. This way, your whole process is captured so anyone can run it using one simple command and the results will be consistent.