4 ms·

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 vi

• tamiral 3y ago
  most places i've worked at had no semblence of data flow diagrams!
• forinti 3y ago
  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 3y ago
    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 https://github.com/jcbhmr/ezmdpage [2] https://github.com/obaqueiro/mermaid-js-auto-renderer https://github.com/obaqueiro/mermaid-js-auto-renderer
    • Hel5inki 3y ago
      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 3y ago
        Swagger is not documentation, it is is a way to generate executable API examples from code comments.
    • Chris_Newton 3y ago
      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 https://en.wikipedia.org/wiki/Literate_programming
  • photonthug 3y ago
    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.
  • Chris_Newton 3y ago
    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.
• deleted 3y ago
  [deleted]
• tokamak-teapot 3y ago
  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.