Ask HN: Is there a good framework for an interactive user manual?

Could you do it totally on the client? That is, draw a form and then have a Javascript fill out the template values (say <span class="field_name" />)

It wouldn't he hard to make up Sphinx directives to drawn the form and put in the target spans.

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.

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’m not sure if ObservableHQ will satisfy your other tool requirements. And I haven’t tried the export for myself. I built my first notebook a few days ago and was very impressed.

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.

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.

After 6 months of hunting I’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’s built with python but you don’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/

Since you’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’re looking to use web tech because that’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?

Svelte+mdsvex was my choice for my blog. Easy to setup, and you can just write markdown, with svelte templates.

I.e. ``` <script> var ip = "127.0.0.1" </script> <input type="text" bind:value={ip}>

*Your select ip address is {ip}.* ```

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.