The magic of DocOps
DocOps
Our doc site for the AgileData App & Platform is built based on “DocOps”.
I create .rst files with the documentation markup in VS Code, push it to our Google Cloud Repo (Git equivalent) and it automagically triggers a rebuild of the docs.agiledata.io site.
We run two sites, an internal Kitchen site where I review the docs to make sure they are ok, before we publish them to the external Docs site.
Support collaboration
There are a small group of us that create these docs.
The awesome Jana Barth who takes my short Gone in 60 Seconds product overview videos and turns them into awesome user guides.
The plumbing magician Nigel Vining who does the first cut of the release notes for new features.
Support automation
This is an interesting process in itself, as we hold all the release notes in a Google Sheet and a nifty little python script runs through them and automagically generates the .rst files for each release note when needed.
I tend to review both sets of content, and also create a bit myself, when I make the time.
Version everything by default
All this content is versioned and managed by the git-ish workflow.
Still a technical task
I hate git. I hate the push-me, pull-you, flow.
I know I should always commit my stuff regularly, even when its not finished, but I don’t.
And then of course when I do try and commit my changes I get sodden red messages with sodden merge failures.
Thats why we built versioning into the AgileData App and Platform itself.
I don’t want to have to deal wth the complexity of managing versions and changes using the complex git-ish stuff.
And yes I know that lots of people can use git properly, and its more about me, my way of working, and my lack of technical skills in this space.
But I think there are more people like me out there.
Versioning should automatic and magical
And I can’t see why we cant make the AgileData App remove that complexity for them.
They should be able to make changes to their transformation rules, those changes should be versioned by default and those changes should be able to be tested before they are published.
All without having to push-me, pull-you or seeing a line of git-ish code.
Now IMHO that would be simply magical!