
Ask HN: How to keep process documentation up to date? - playbook_ops
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.<p>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!
======
stargrazer
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.

~~~
playbook_ops
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.

~~~
stargrazer
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.

------
cimmanom
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.

------
stargrazer
[https://news.ycombinator.com/item?id=18674158](https://news.ycombinator.com/item?id=18674158)
is a recent HN on one company's view on documentation.

