Is there a good framework for an interactive user manual?

Question

I need to deliver a technical user guide for field technicians to follow for configuring some devices. The current solution is a word doc which requires some brain power to fill in appropriate values (naming, IP, etc) as you progress in the steps.I'd like to replace this with some kind of self-contained HTML where they can fill in the "variables" at the top and have it auto-generate throughout the doc. This is pretty simple with HTML/JS, but the code can get messy if not done right.Is there some framework like ReadTheDocs where I can easily write out RsT or Markdown, inserting variables with jinja2 (as an example) that can be input in an input field, and have it dynamically render live in-browser (which I believe then rules Sphinx out)?

evolve2k · Accepted Answer

After 6 months of hunting I&rsquo;d now strongly recommend Material for Mkdocs. You end up with markdown split into logical folders, with a natural flow from each page to the next built in.It&rsquo;s built with python but you don&rsquo;t need python knowledge at all to build; configure and serve the product.The plug-in eco system adds the ability to embed variables into the markdown pages also you can embed html, so d3 visualisation or a vue calculator app will all embed just fine.Really clean extensible base, insanely simple and fast to get started oh and free to use. I push mine to GitHub and have that auto build into GitHub pages or a free Netlify account.https://squidfunk.github.io/mkdocs-material/

jitl · Answer

Online data visualization notebook ObservableHQ does a great job interpolating dynamic values into very nicely formatted Markdown. It also has an export system. You can download all your content and the open-source runtime. That could work for distributing a single-offline-html-file with your finished notebook embedded and rendered: https://observablehq.com/@observablehq/downloading-and-embed...I think you could port your Word doc to ObservableHQ and wire up the forms & variables in an afternoon. But, I&rsquo;m not sure if ObservableHQ will satisfy your other tool requirements. And I haven&rsquo;t tried the export for myself. I built my first notebook a few days ago and was very impressed.

AngusH · Answer

I once wrote a software release checklist system with custom values in php which worked quite well, if you have a server to run it on.
But I'm not sure thats the best bet for new work today.
It might be worth looking at interactive fiction tools like https://twinery.org or https://www.inklestudios.com/ink/
They sort of do everything you need already including variable ui+storage, javascript processing, html output and save/reload.
Twine also supports complete backtracking if you use the sugarcube dialect.

orev · Answer

Since you&rsquo;re already using Word, why not use what it has? The Developer tab provides multiple input controls, and using those values should be fairly easy in the document. You can have a section at the top where they fill in the values (or pull downs, etc.), then reference those fields in the document. You might need a little VBA, but this should be pretty simple.It sounds like you&rsquo;re looking to use web tech because that&rsquo;s what you know, maybe not right for the job though. Do you really want to ship a whole JS framework just for people to RTFM?

nicbou · Answer

I do this in HTML with Vue. It lends itself pretty well to building calculators. Those calculator templates are self-contained, so I just use them all over my website.
See here: https://allaboutberlin.com/tools
Perhaps there are tools that do this, but the use case is fairly simple: variable substitution based on user input. For that, I'd stick to simple, client-side tools.

eg312 · Answer

I'm working on https://reactivedoc.com/ - it's markdown + some custom widgets, and you can export it as a self-contained html file.I made it to solve my own problems: document commands & scripts and replace parameters with user input values. Soon I will release a new version with simpler syntax.

powmonk · Answer

Any e-learning platform would be capable of this. Using something like Adapt to author it and Moodle to host it you could easily create documents without messy code and still input and manipulate varibles. I think Adapt may even be able to output HTML5 courses, so you may not even need Moodle. It's been a while.

danbulant · Answer

Svelte+mdsvex was my choice for my blog. Easy to setup, and you can just write markdown, with svelte templates.I.e. ``` var ip = "127.0.0.1" *Your select ip address is {ip}.* ```

PaulHoule · Answer

Could you do it totally on the client? That is, draw a form and then have a Javascript fill out the template values (say )It wouldn't he hard to make up Sphinx directives to drawn the form and put in the target spans.

Is there a good framework for an interactive user manual?

I'm working on https://reactivedoc.com/ - it's markdown + some custom widgets, and you can export it as a self-contained html file.
I made it to solve my own problems: document commands & scripts and replace parameters with user input values. Soon I will release a new version with simpler syntax.

Svelte+mdsvex was my choice for my blog. Easy to setup, and you can just write markdown, with svelte templates.
I.e. ```
Your select ip address is {ip}. ```

Could you do it totally on the client? That is, draw a form and then have a Javascript fill out the template values (say )
It wouldn't he hard to make up Sphinx directives to drawn the form and put in the target spans.