Ask HN: What do you use to automatically keep documentation up to date?

8 points by T-Winsnes 3 years ago | 4 comments

As we are moving faster, and cloud deployments are getting more complicated, keeping documentation up to date often falls to the wayside.

How do you keep your documentation up to date?

What do you use for automating documentation and architecture diagrams, and how come?

I would love to know more about what you struggle with and how you tackle these thing where you work.

Disclosure: I'm the CTO of hava.io and we are trying to solve automating architecture diagrams

pxska 3 years ago |

I remember a thread a while ago on here, where the top reply was something along the lines of: "Every person is responsible for a handful documentation topics/threads/articles and whenever someone uses the documentation and finds that it's aged, they ping the person in charge of the article and their task is to either renew it or find out a solution to renew it."

That isn't exactly the answer to your question, but I believe it is a very good idea to live by.

As for my personal experience, we just ping a Slack channel whenever an article is old and has to be renewed. But we also don't have a very big company, which means not a lot of documentation articles to monitor.

unop 3 years ago |

Documentation-as-an-artefact of the continuous delivery process - every feature is feature-complete only when counterpart documentation is generated and integrated/built as part of the pull-request procese.

I.E. A code/solution review must also consider the documentation alongside the feature or solution.

This implies that the documentation is (held beside) source code too and can be diffed/compared e.g. Markdown for text, mermaid/graphviz for diagrams and that this can be built, rendered or published easily/readily (Hugo, zola, etc)

ThePhysicist 3 years ago |

I think the future are frameworks that auto-generate large parts of the documentation, possibly with small annotations that can be directly done in the code. You see this with libraries like FastAPI, which uses type annotations to auto-generate a lot of the stuff that was created manually before. I think it's the only way to keep docs in sync without expending a large amount of effort.

shyn3 3 years ago |

This for on-premise would be a dream.

Definitely want to use your product in the future.