Ask HN: Is there a good framework for an interactive user manual? | Hacker News Reader

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

24 pointscore-utility12 comments

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)?

View on HN

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/

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.

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.

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?

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.

Correct link is https://allaboutberlin.com/calculators I believe.

Yep. I was working from memory. Thanks!

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.

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.

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}.* ```

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.

This is effectively what I'd like to do. I guess I'm almost just looking for a nice UI/frontend to help make it.

Reply on news.ycombinator.com