Re:Ask HN: Is there a better way to document complex softwar...
by sien on Sunday November 25, 2018 @06:31PM
(#18529775)
It's already there with Terraform but it's not that pretty yet:
Re:Ask HN: Is there a better way to document complex softwar...
by qznc on Monday November 26, 2018 @03:32PM
(#18536537)
More evidence that graphviz needs a successor or makeover. Some force-based post-processing with the additional goal of rectangular borders would be good. Also some tweaks like little arcs where lines cross and shadows for boxes.
edit: Most of the responses to the original post seem to be addressing the idea of understanding code through diagramming. I am _much_ more interested in understanding complex infrastructure through diagrams. What queues do we have, what are the producers, what are the consumers? Where is the database? What writes to it? What do we shard on?
Code's a lot slipperier to autodoc, and the slipperiness is a function of number of contributors.
Infrastructure, however, we have been herding (pun intended) to a more declarative, predictable paradigm for years which is great. So let's start building the auto-documentation stuff into e.g. Terraform, since infrastructure-as-code seems like the natural place for such useful side effects of provisioning assets.