Hacker News Reader

Comment by stargrazer | Hacker News Reader

Maybe automate some of your infrastructure?

I've found that running everything via SaltStatck scripts helps to keep things scripted and documented: as in, the scripts are the documentation (build and maintenance notes are inherently part of the 'process code').

Then apps like dot and similar can be used to build links from the code and attribute files.

That is, attempt to build 'single sources of truth'. And then use tools to 'view' the relationships from their original sources.

By testing the scripts and using the scripts, processes and docs are inherently kept up to date.

Rigorously use the scripts and don't do things manually.

View on HN

That is helpful - could you explain more about what you mean by using dot to "build links from the code"? I've used dot for process documentation in more of a business process / workflow sense but haven't heard of it in this usecase.

Zooming out, I am thinking more of "business" workflows here vs. technical steps - things like capturing our hiring and on-boarding processes for example.

For 'dot', I was considering more the machine inter-relationshps. Given ip addresses and subnets and interfaces in the configuration files, these relationships can be diagrammed given the 'sources of truth'.

SaltStack files have state files (commands and general configs) controlled by a 'top' file which lists hosts and their configurations. SaltStack files have pillar files (configuration parameters and values unique to device being configured) controlled by a 'top' file which lists hosts and the parameters. These relationships could be mapped by dot as a visual path through relationships.

Making a giant leap into the realm of general documentation, in a similar vein, document various pieces of the work flow as separate entities, where the documented entities may be common to several different work flows. Workflows then become linked version of various entities. And dot can generate work flow diagrams.

This all requires organization and effort. In hindsight, I've suggested doing documentation as though you are writing a software program. I'm not sure if tooling exists to do such a thing.

Take it all with a grain of salt. So to speak.

Reply on news.ycombinator.com