I want to lead an Angular + NodeJS project. As this is my first experience, I thought about using UML diagram as both designing/architecting the project and also the project's documentation.

But I am not sure if using UML diagrams is a good idea? I mean it takes longer time and many details that I don't know if is it necessary to writing them or not? I say this because in previous projects that we worked on, we were just talking about things we want and each member could do the task by his/her understanding, but at this time I decided to do the next project more organized with more developers, but don't know how much of detail or abstraction is enough and from where it's redundancy and not necessary?

I also though if I use UML diagrams in designing/architecting stage, we can also use this design as our project's documentation too and we won't read much documentations in the future, but I don't know if I think true or not?

I should mention we are a startup like company with 4-5 guys looking for extending up to 10 or more developers.

  • I think for a group that small you can go with the suggested answers below. But if you have to do it for a really large company there is no way around UML. It's a stony way and I can understand why people moan and struggle. But at a certain size code is NOT the solution. – user188153 Dec 16 '20 at 21:01

UML diagrams can be a great tool for designing an application, but there are limits. Class diagrams communicate the structure of code. Sequence diagrams communicate a specific interaction between code modules. Use case diagrams communicate the higher level business process.

To design a single use case in your application might involve 3 different UML documents if you want to completely document the design. Furthermore, don't design too far ahead. Learn from agile development, and don't do a Big Design Up Front (BDUF).

Judge the skill level of your team to identify which UML diagrams are useful for implementing the application, and stop there.

Long term, UML diagrams are a terrible way to record the current state of the application. Rely on code for this. UML diagrams are an artifact of application design. Something created, and then stashed away without being updated again. Sure you can say part of maintaining the application is updating these documents, but then you spend as much time updating UML diagrams as you do building the silly thing to begin with. The moment you finish a feature, the UML diagrams are out of date.

So, use only the UML diagrams the team finds useful. Create them to communicate the design, just as you would a mockup for a new web page or application screen. After the feature has been implemented, treat it as a design artifact that sticks around for historical purposes. These diagrams can be updated as the team sees fit when new features are added, or existing features are changed.

One last word of warning: do not spend time updating a UML diagram when analyzing code can answer the same questions. It's a trap. You'll spend 3 days pouring over a class diagram only to discover something was accidentally omitted.

  • You obviously never had to manage a large SW project. Truely keeping code and UML in synch can be a nightmare. But not doing it will end in just a bigger fail. – user188153 Dec 16 '20 at 15:16

I would say don't bother with a big modelling phase (with or without UML); the diagrams get out-of-sync with the code too quickly - it is a huge drain to maintain them. Let well factored, modular and clean code be your single source-of-truth. Certainly in a startup where you need to get working product out quickly so you can pivot and iterate and make money!

It IS however worth knowing how to do the main UML diagrams (class, sequence, state), and use them when working on a design issue, or in a meeting. They are useful to explore and communicate a design. But don't plan to keep them.

Going off topic, I'd say it's important that all your team can communicate (words and sketches) the architecture/design in 5 minutes; be able to explain what it does and broadly how.

I used to do lots of UML in the days of RUP, with all the tooling. I spent more time fighting the tool, laying things out "just so" rather than delivering value, fighting the impedance mismatch between UML and Java/C++.

Stick to the real meaning of agile and you'll be ok; people over process, keep close to the customer, etc. And refactor mercilessly (protected by tests) as your understanding improves.

Not the answer you're looking for? Browse other questions tagged or ask your own question.