Write Interactive Documentation with Templates and Parameters

alex adam
3 min readJan 25, 2022

--

Let’s say you want to do a local port forwarding via SSH, but you don’t remember the command. You do a quick search on google and find something like this:

ssh -L 8080:localhost:80 user@10.20.30.40

But, in your case, the SSH server doesn’t run on the standard port, so you have to specify the custom port. You do another quick search and assemble the full command (in your head or in a text editor that acts as a buffer):

ssh -L 8080:localhost:80 user@10.20.30.40 -p 1234

Now you have a generic example, and you have to replace the key parts in the command to make it work. So you have to replace the local port, remote port, remote user, remote ip and the SSH port.
A few copy-pastes later and you realize you forgot how it works: local_port:ip:remote_port OR remote_port:ip:local_port ? Google saves you again:

ssh -L LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER

You just spent 10 minutes gathering or refreshing some valuable info. You also spent valuable time on editing or copy-paste parts of the command in order to customize it.

ReactiveDoc can help you write documentation with templates and parameters. Why is this useful? Because it saves you a couple of minutes next time you’ll want to reuse this command.

Let’s start with the basic command as a template:

Add some basic explanation from https://linux.die.net/man/1/ssh and a link to this excellent resource

Then add a Number Input, and change the label value to “Local Port”, variableName to “local_port” and set 8080 as defaultValue, like this:

In the command template, replace 8080 with{{local_port}}

Now, add a Text Input for the destination IP, then replace ‘localhost’ in the template with the{{destination_ip}}variable:

You can extract each command’s part as a parameter:

Export this document as an HTML page and, next time you want to do a SSH port forward, just open it with any browser, set the parameters, click on the ‘copy’ button and paste it in a terminal. 2 minutes saved!

You can also share this HTML file with your team (they don’t have to install anything to run it — it works in any browser) or host it on a local server as a static page.

Try ReactiveDoc Now!

--

--