Ask HN: Documentation and diagrams versioned with code – how to handle diagrams?

7 points by BattyMilk 5 years ago | 7 comments

We store our software technical documentation along with the code in markdown files in the git repository - our definition of done requires that developers keep this documentation up to date.

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

mdpm 5 years ago |

https://app.diagrams.net/

Versioned, text format diagrams.

Alternately as mentioned, the mermaid DSL or similar, but this is daunting for non-technical users. I'm more a fan of having people be able to think and communicate visually, as the technical users are both the least likely to need the visuals, and if capable of creating them, the visuals are less valuable.

Mermaid is a great output format for documentation though if you're rendering these from API/code.

PaulHoule 5 years ago |

It's a big problem that people have been working on for years, if there were good solutions then UML would have a much better reputation than it does.

My take is this.

Some of the content of the "diagrams" can be derived from the code (for instance you can get the methods and fields names and types of a Java class) There is certain extra metadata that it takes to make a good diagram that could be stored in a separate file in a textual format which plays well with version control. A generator script puts it all together to make the images.

Some of that metadata is: do we draw this object? where do we draw it? how do we route lines to connect it to other objects?

i think you need to be able to make more than one diagram (a UML of 100 database tables takes up most of a blackboard panel, a diagram that shows how 5 tables work together to support a user story is golden)

there is a tension between automatic layout and routing which will usually be unacceptably bad and manual layout which is a lot of work (I love boxes & arrows in Powerpoint except for the Bézier curve connectors... then I learned my favorite anime illustrator doesn't know how to draw anime characters with Bézier curves either.) This is an area where you need to find a compromise that works.

In the 1990s there was interest in tools that could parse some code, manipulate it in a UML-like interface and round trip it back to code with whitespace and comments intact so that it makes changes about the same as a professional programmer would that you can check into git just like another team member.

That path requires unusual compiler technologies, but you can also use canonical sort orders and similar tricks to make data in some format like YAML evolve in a way that plays nice with git.

edoceo 5 years ago |

We use PlantUML for all the things. Works nice with asciidoc. Gotta spend a day tweaking the styles tho

hm-nah 5 years ago |

You can use Mermaid in your markdown files.

rossmohax 5 years ago | |

I second this. Gitlab supports Mermaid out of the box, which helps

lock-free 5 years ago |

Ask the CAD industry how they handle design files. VCS isn't really designed for this. The closest thing is to make sure diagrams are generated from code.

probinso 5 years ago |

I use graphvis, I'll probably be looking into mermaid after this though, I had not heard of that