11 ms·

Quick question that I only ask because of my 30-odd year history as a corporate contractor... Does anyone here really use those UML-based docs to actually lear

• avip 8y ago
  It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.
  • pvorb 8y ago
    I second that. Reading tests is often more efficient than trying to learn about a system through documentation.
    • trading_wheels 8y ago
      maybe - but the codethat's the hardest to understand (age, size, immature) is often the least tested, or worse the tests have been gamed over time because the previous assumptions are no longer relvevant & the code has changed so much new developers just want them to pass. related aside - In my experience developers are much more likely to cut out old code than they are to remove or refactor irrelevant tests
  • artwr 8y ago
    Ha-ha, the joke is on you, the systems I have inherited do not have tests. Joke aside, tests are a great resource when they are present. The other technique I have used was to look at the system like a black box, and only look at the expected behavior at the boundary. Sometimes, it is the fastest way to clear old cruft.
  • sjellis 8y ago
    These days I preach the gospel of the project README: One file, Markdown format, versioned with the code, that says what the project does with high-level concepts, and how to build it and run the tests.
• henrik_w 8y ago
  I've been developing software professionally for 25 years. I've never found them to be useful. Even if you have them, they're usually out of date, and anyway they don't really help answering the questions you have. None of the places I have worked at have put a lot of emphasis on UML diagrams.
  • Pamar 8y ago
    Ditto, except that I have 30 years professional experience.
  • PopeDotNinja 8y ago
    I tend to write up (not necessarily formal UML) diagrams in 2 cases: 1. I'm brainstorming with myself about how I want the software to behave 2. The software is basically done & tested, it's unlikely to change, and communicating the behavior to other people is of value, especially when describing a system that spans multiple components
    • trading_wheels 8y ago
      I'll add (3) When I'm learning a new system, especially if it's big and/or old. The idea is that if I go to the trouble to document it then the next person won't have to; this is seldom the case because as stated above the get out of date so fast. It's still a great way to learn and confirm your understanding though.
      • rorykoehler 8y ago
        (4) Security audits
  • cs02rm0 8y ago
    Just 15 years here. I've worked at somewhere where they did put a lot of emphasis on UML diagrams. To the point they had a product where some of the code was generated from UML, not once moving from the initial design to code, but repeatedly every time the design became out of date. It became the project everyone tried to get away from and project all new joiners were thrown into the deep end on, many quitting as a result. A couple of years ago I interviewed for a contract role with a sister company and they waxed lyrical about their love of "best practice" UML in the interview. I declined the offer, I'm too old for worrying about which arrow type to use when no one reading it's going to understand the significance anyway. I think there are a lot of attempts to move away from code because it's complex, but the bottom line is it's the best we have for now.
• klohto 8y ago
  I'd like to support this statement that I do not remember the last time I used them as well... Most of the time, they are accompanied by company (or team) specific TLAs that I do not understand, at the time of starting, anyway. For instance, 1 year ago I joined NXP, which is a HW oriented company. I tried to study the UMLs, which for instance, described how CMSIS packs are delivered and how they are split into DFPs, BSPs and SWPs. At that time I had no idea what the documentation is about and I've rather started incrementally building my mental image of the whole system. Looking at the UMLs now, I understand them, but I can still clearly see that they will only confuse a newcomer.
• jordache 8y ago
  They are useful in articulating high-level insight on how systems integrate together. A well done diagram would have an as of date, and some commentary along side boxes.
  • trading_wheels 8y ago
    >> A well done diagram would have an as of date maybe we should promote a "best before" date for technical artifacts...
    • jordache 8y ago
      How would author anticipate the freshness of that diagram? Not possible I say
• mikevin 8y ago
  This is why I dislike it when technical documentation itself becomes a goal. Detailed documentation never seems to be up to date in the real world. I've had far better experience with concise documention about high level concepts and structures and diving into the actual implementation for any details.
• mattlondon 8y ago
  UML Sequence diagrams are useful, if they are kept up to date and reflect reality. I find they are great for the initial "what the hell is this doing?" stage of coming to something new.
  • xtracto 8y ago
    The best way I like documentation is via a docs/ directory within the repo. Uing js-sequence-diagrams ( https://bramp.github.io/js-sequence-diagrams/ https://bramp.github.io/js-sequence-diagrams/ ) to create self-contained one page diagrams (like this https://jsbin.com/jusiyusowu/edit?output https://jsbin.com/jusiyusowu/edit?output ) which go into code. That allowed me to include documentation updates in the code review.
• ChrisCinelli 8y ago
  Completely agree. Systems change, people that work on them change. A diagram gets obsolete very quickly. A diagram is mostly valuable in the design phase for me and to have faster less ambiguous discussion with people. In the systems that do not drastically change, it is sometimes useful later to understand how the system was initially designed by new people. But for specific part of the system I always have to look into the code on source control. Git blame and diffing commits have become the only good tool able to tell me what I need and also help me to realize what changed overtime, by who and when. I remember seeing some version control tools for diagrams but unfortunately unless the design is updated as the code gets updated, these tools are worthless. Comments that are in the code get outdated. There is little hope with diagrams. The exceptions are tools that get their data from the system. In a company I was working long time ago, we had a GUI to connect parts of the systems. The changes in the UI became real changes in the system. That data was always updated. For MySQL databases in the past I used a tool that was able to create the table diagram from the schema in MySQL but I had to spend quite some time to rearrange the tables with drag and drop. It worked of if people defined foreign keys and kept the naming consist.
  • jonwhittlestone 8y ago
    For groking relational databases and schemas, I find Dbeaver is good for producing an entity relation diagram in relation to a specific table (as well as an overall ERD)
• p1necone 8y ago
  Planning is highly useful, plans are useless.
• ryanSrich 8y ago
  In certain cases they are required. For example - compliance audits of varying flavor require architecture diagrams. To be clear, I expect that auditors understand less than 1% of what they look at in a diagram or why certain systems look the way they do, but it is a requirement none the less.
• luckydata 8y ago
  I would use them if they existed. I usually spend the first couple months of my tenure with a new team documenting the product after I ask a few questions and inevitably people start giving me answers that are rarely consistent. After those diagrams are created, usually everyone is SHOCKED that discussing the system becomes so much easier. Unfortunately, modern software teams don't value documentation and that's the source of a lot of miscommunication, slowdowns and frustration.
  • pojzon 8y ago
    "WORKING PRODUCT, over comprehensive documentation" Software changes too fast to make a static snapshot of it. Its the same with comments in the code, few months later what was there is no longer valid and only creates confusion. But i can understand managers dont like that because it makes it harder to replace ppl.
    • zeroname 8y ago
      > Software changes too fast to make a static snapshot of it. Architectures don't really change that fast or often, except maybe in the initial phase. That's why most UML diagrams are a waste, they are concerned with low-level details like classes or internal interfaces.
      • ako 8y ago
        Agreed, the architecture diagrams I usually look for are high level, mostly about how different systems are connected. These don't change that much. When looking at architecture diagrams, usually you don't want them lower level details anyway, they would just obscure the big picture.
• bluGill 8y ago
  I have. When they are up to date they are useful and easy. There is only one time I've seem them up to date: the UML was used to generate the headers (we used C++ at the time). If the build process doesn't force the UML to be kept up to date, then you should only do white board uml: draw the diagrams on a whiteboard, and erase the whiteboard two weeks latter.
• hyperpallium 8y ago
  Yes. - But is "out-of-date" the problem? "round-trip" UML tools, auto-generating UML from code, seemed like a great idea once (e.g. Rational, Together), auto-keeping UML up-to-date. They don't seem popular now. - Is UML the problem? (IMHO: no. It's good enough to be useful; like, no matter how bad XML is, it does work). - Or is it that the devil is in the details, and you just can't summarize code? IMHO, docs of architecture would be the most useful of all docs. Design patterns, javadoc-like tools, type-systems and UML all try it. In the end, understanding the domain problem is the key to understanding the solution approach, which is key to understanding its architecture. That's a lotta understanding. In practice, I inspect source, stepping through manually - your way's better.
• stackzero 8y ago
  I really appreciate having a high-level diagram of system architecture when joining a new project. It gives me an instant feel for whats going on and even if its slightly out of date it gives context to the evolution and design decisions of the codebase since then. That said, there's nothing that beats the good ol' step debugger and diving into the code first hand. They're complementary. Without the diagram its kind of like building a mental model of a room by feeling it out in the dark. Edit: I'm not too strict on UML exactness, as long as it gives a feel for the components, data flow, etc.
  • profalseidol 8y ago
    And when you can't debug... since no person in the company can build the code in Eclipse, or run it locally.. you look at the gigantic logs full of soap xml dumps. At least that's my experience.
• DomreiRoam 8y ago
  I worked on a project that needed to implement regulations specified in legal documents. An analyst did work on reading hundreds of pages of legislation to extract UML diagram representing the objects and their relation sand also all constrains defined by the legislation. In this case, it was quite useful to have UML as an intermediary and not force developers to be jurist. The UML documentation was checked and validated by expert of the domain.