How to go about documenting your setup?

How to go about documenting your setup?

Possibly the single most important thing that separates science from "fiddling around" is documentation. Figuring out how to document things is often non-trivial and me telling you that "unless you wrote it down, it didn't happen" only goes so far.

If documentation isn't your thing, what about "I broke something and I don't know how it was before I fiddled" as an incentive instead?

Recently I had cause to explore how to document how my station is configured. To give you a sense, the microphone is connected to a remote-rig, which is connected to a Wi-Fi base station, over Wi-Fi to a Wi-Fi slave, to another remote-rig, to the radio body, to the VHF port, through two coax switches, a run of RG213, to an antenna.

When receiving, it goes from the antenna, to a run of RG213, through two coax switches, to the VHF port, to the radio body, to a remote-rig, to a Wi-Fi slave, to a Wi-Fi base station to a remote-rig, to the remote head, to a set of headphones.

Of course, at this point I've written it down, so, job done .. right?

Well, what about the data connection, the external speaker, the remote head display and other goodies, say nothing of the duplicate devices with similar names. All in all, the FT-857d has something like eleven ports, each remote-rig has ten, so just wording it is a start, but hardly qualifies as documented.

What if we drew a picture instead? At this point you could pull out your crayons and start scribbling on a sheet of butcher's paper and that would be a fine start, but it would be difficult to share with me or anyone else and updating it would be a challenge, let alone versioning it.

As it happens, we're not the first people to have this issue. In the 1980's and 1990's researchers at Bell Labs were trying to figure out how to draw graphs and from that work a language, 'DOT', since everyone is a fan of the "DAG Of Tomorrow", and a series of tools, which today are known as 'Graphviz', made the visualisation of relationships possible without the application of coloured wax on dried cellulose fibre.

In my other, computing job, I had cause to visualise the relationship between a million or so nodes, allowing me to discover a specific node that was directing all traffic, where I could insert my debugging code, but it was only possible thanks to these free and open source tools.

While the DOT language isn't particularly complex, it occurred to me that for someone not conversant with the syntax, we can start even simpler with a CSV text file that shows the relationships between each device and convert the CSV to DOT and in turn to a picture.

For example, I documented the relationship between the radio and the antenna by adding five lines to a CSV file, essentially, FT857d to VHF port to VHF coax switch to VHF grounding switch to RG213 to antenna.

In all, to document everything except power, since I haven't decided how I want to describe it, I used a CSV with 47 lines. On the face of it, that might sound ridiculous, but I can tell you, it shows all the sockets on the FT857d, all the sockets on both remote-rig devices and the relationships between them. With it anyone can duplicate my set-up.

Having previously spent some quality time learning various aspects of the DOT language, I figured I could write a little script to convert CSV files to DOT, but being of the generation of software developers with the attitude, "Why write something if someone else already did?", I discovered that Reinier Post at the Eindhoven University of Technology has a delightful collection of scripts, including one appropriately named 'csv2dot'.

Written in Perl, the only language that according to some looks just as impenetrable before and after encryption, the tool works as advertised and makes a DOT file that you can then visualise using Graphviz.

Of course there's Python scripts lying around that claim to do the same, but I wasn't keen to install the kitchen sink just to try them. Instead I made a quick little Docker file that you can find on my vk6flab GitHub repository that will walk you through this, complete with my example, so you have a starting point.

Now, I used this here to describe my station, well, one part of it, but it can easily extend to document your entire station, and because we're talking about text files that contain the information, anyone with a copy of a text editor can update the file when things change, since that's where the real magic happens.

So, what are you waiting for, documentation?

I'm Onno VK6FLAB