Ask HN: Documentation and diagrams versioned with code – how to handle diagrams?
Often, documentation needs supporting diagrams and we don't really have a clear defined way on how keep our diagrams up to date. As a result, documentation in some repositories link to a gliffy diagram and some include a png.
Neither are ideal:
- Gliffy diagrams outside of the repo are not versioned with the documentation and are not immediately visible in PRs so we risk the diagrams becoming out of date
- PNGs require a lot of effort and unless we include an editable file to spit out a png, devs will have to manipulate the existing PNG which becomes a bit messy - if we do include an editable file, it would mean an additional large file living alongside the code and PRs would be messy everytime it was updated.
I'm assuming we can't be the only organisation who has encountered this issue. Are there any tools/processes you could recommend? I'd be interested in hearing anyone's approach to technical documentation. Are we just approaching technical documentation in the wrong way?
Cheers