Ask HN: How to keep process documentation up to date? | Hacker News Reader

Ask HN: How to keep process documentation up to date?

15 pointsplaybook_ops5 comments

What are the best practices for keeping documentation up to date? I find that our documentation is siloed across Visio, PPT, text docs, tribal knowledge, Quip, etc and never unified... this creates a huge headache when dealing with scenarios like on-boarding new team members, shifting responsibilities when someone is out, or just keeping everyone on the same page.

Realize that a large part of this is just being organized and disciplined but wondering if HN knows any good tools or best practices to address this? Thanks!

View on HN

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.

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.

1. Make “getting all our documentation in one place” a project. This will probably involve more decision making effort than actual time, if you already have the docs. The actual consolidation will likely be mostly copy and paste.

2. Make “getting our docs up to date” a project. Time required will depend on how many docs you have and how far out of date they are.

3. Create an index for it and a “getting started” guide composed mostly of links to other docs. Should only take an hour or so to write.

4. Make “update the docs” an official step required for any process change.

https://news.ycombinator.com/item?id=18674158 is a recent HN on one company's view on documentation.

Reply on news.ycombinator.com