Automatic Wizards, from Markdown
READMEs are a great way disseminate broad knowledge, but can often be a frustrating way to accomplish a specific task. Documentation is prone to rot. Screenshots and command lines invariably go out of date. Sometimes a README may never have worked as written, due to gaps in the documented tasks, divergences from the implementation, or incompletely specified prerequisites.
Even for complete and up-to-date READMEs, it is often unclear how to turn the documentation into a reliable plan of execution. Which code blocks are optional? Which have I already done on my laptop? How about in my cluster? How much of the overly general documentation is relevant to my system?
madwizard automates testing and consumption of documentation. Point
madwizard at markdown, and it can generate an execution plan, and
help you (and your users) execute these reliably.
The madwizard User Experience
With madwizard, several interaction modes are possible.
-
Task Graph Library: point to your markdown documentation and
madwizardgenerates an execution plan. -
Test Rig: you may use
madwizardto run through that plan in an automated fashion. -
ASCII CLI Wizards: a
madwizardplan allows for choice, and includes an executor that interrogates the user using a familiar terminal Q&A experience, enlisting their help in guiding the plan. -
Graphical Wizards: the wizard executor supports inversion of control, whereby a Q&A exchange may be intercepted and presented with a custom, e.g. graphical, interface.
Installation
npm install madwizard # consume as a library
npm install -g madwizard-cli # consume as a CLI toolThe CLI package includes a copy of the guidebook
store. If you want to roll your
own collection of guidebooks, you can install madwizard-cli-core,
which is the same, but without a copy of the guidebook store.
Kicking the Tires
After installing madwizard-cli, you can try some of the demo guidebooks:
madwizard demo/hello
madwizard demo/choice
madwizard kubernetes/choose/ns