[tdba]

The general competency level of diagramming in most engineering teams is low enough that I think it's better to talk about what to diagram rather than how to visually lay it out. Everyone has heard of sequence diagrams (and for good reason!) but do you use data flow diagrams?

https://en.m.wikipedia.org/wiki/Data-flow_diagram

[forinti]

I studied Structured Analysis at university and still have a couple of books on the subject, but I never used it professionally.

I had a lot more experience with UML, but that too has gone out of fashion.

Nobody models anything anymore, not even ER diagrams are used.

Knowledge ends up scattered between a million tasks in some project management software. Often, things are not even written down, because "there's not enough time".

[xtracto]

One of the things I recommend to the startups I advise is to include documentation within the repository. I always try to have a /doc directory which includes Markdown (I like using [1] self rendering markdown pages) and MermaidJS (For which I also created a dumb self rendering script [2]).

That way Merge Requests can be blocked for lack of documentation, or lack of documentation update.

MermaidJS have been a godsend for documentation.

[1] https://github.com/jcbhmr/ezmdpage

[2] https://github.com/obaqueiro/mermaid-js-auto-renderer

[Chris_Newton]

One of the things I recommend to the startups I advise is to include documentation within the repository.

Agreed, this can help. I sometimes wonder, having written a substantial project in literate programming¹ style once, whether that approach doesn’t deserve more exploration. Then not only is your documentation kept in the same repo as your code, your source files themselves almost become documentation first and code second.

You definitely have to do a lot of things quite differently to how we typically do them today to make that idea work well, but I suspect it could be like a good static type system, incurring a modest extra cost up-front but with a big long-term pay-off once you’ve figured out the tools and processes to take advantage of it.

¹ https://en.wikipedia.org/wiki/Literate_programming

[Hel5inki]

This is interesting, do you have an example repository with that setup? My team currently uses Swagger for documentation which provides decent documentation for us, so what sort of documentation at the repository level could I gain by using this setup instead or in combination? Also, how would one detect that the documentation has been correctly updated aside from manual inference?

[fijiaarone]

Swagger is not documentation, it is is a way to generate executable API examples from code comments.

[Chris_Newton]

Often, things are not even written down, because "there's not enough time".

This one is the epitome of the “If you think X is expensive, try [not doing X]” meme.

I’d take a decent software architecture diagram, a detailed data model with an ER diagram, and some form of useful written requirements over probably any other process or tool ever invented in the world of software. Alas, advocating such things in the era of Agile often feels like the curse of Cassandra.

[photonthug]

Oh man, if only it were just the diagrams that were missing. It's shocking how a lot of orgs have to get crazy large before they land on any kind of reasonably formal design-process.

[tokamak-teapot]

Yes, though I don’t use the symbols suggested on that page as they don’t connect with people’s mental models very well.

I just overlay the flows of data on other diagrams, adding notes about the type of the data, and sometimes add info about particular fields, where useful.

Where I work it’s also useful to add the internal classification of the data, which allows understanding of the sensitivity level of the data and its retention policy.

[tamiral]

most places i've worked at had no semblence of data flow diagrams!