In 15 years in the industry, the only UML I have seen outside of a classroom has been made ad-hoc, on a whiteboard during a discussion. There would usually be n

In 15 years in the industry, the only UML I have seen outside of a classroom has been made ad-hoc, on a whiteboard during a discussion. There would usually be no strict adherence to whether a square or "blob" was a class, an object, a user, a database or a concept, nor whether a line between these with an arrow at the end meant "inherits from", "knows about", "has an instance of", "sends data to", "calls a function on", "contacts with a network request", "is transformed into" or something else - all these details would usually just be cleared up from the context, or with text next to the lines. There was thus also usually no strict distinction between class diagram, sequence diagram, flowchart or other diagram - the diagram would just be whatever it needed to be in a given area in order to convey the information being discussed. In short it was highly informal, and used as a means of communication or brainstorming, rather than documentation. I have a feeling there might be more UML in parts of the enterprise world, or in places with "architects" that have forgotten (/never learned) how to code. But my guess is the above is what the majority of "UML" usage in the industry looks like. As for your question about documentation: The best advice I can give is to be mindful that documentation tends to get outdated faster, the further away it lives from the code that it documents. That's why "self-documenting" code is so valuable, since the compiler will often refuse to compile it if you don't update it. Thus I would always advise to use the "closest" documentation form that is suitable, in roughly this order: - The code itself - The tests - Comments in the code - Comments at the start of files - Readme.md - Other files in repo - Wiki that lives alongside the repo (e.g. GitHub) - External wiki (e.g. Confluence) In your specific case, it sound like you need to document the architecture/design in a way that needs to be understood before someone would even know which file to look in for further documentation. In that case, I would first attempt to describe the architecture in words in Readme.md. E.g. something like a list of the most important classes/functions/datatypes and a paragraph or two about how each relates to the others. If something like that isn't helpful enough, and you want to make some UML consider using something like asciiflow.com or textik.com to make ascii diagrams to put in the readme. If the info doesn't fit that format, consider making diagrams in images that can be shown inline in the readme - ideally if you do this, use a format where you can also check in the "source" of the image (e.g. a graphviz DOT-file) to make it easier to update. And then finally, if all else fails, you can either check in a PDF, or use a wiki. But as mentioned above - prefer the "closer to the code" solution whenever possible.