[jugg1es]

I can't stress how important it is to get good at writing design documents and producing effective diagrams. If you do not produce these artifacts, it is very difficult for your developers to do what you want them to do. You end up spend way more time re-explaining yourself than you would have spent documenting.

[finder83]

Do you have any advice or tools for diagrams? That's one area I struggle with, and usually have to pull in our designer.

[qznc]

PlantUML if you want to maintain the diagram in version control.

yEd for interactive use because of its auto-layout function. Not unintuitive to use though. It takes some effort to learn.

Enterprise Architect if your company pays the money and you really need its features (e.g. SysML diagrams).

Whatever is close by. For example, we use Confluence for our wikis. It has a Gliffy plugin, so I often use that for embedding diagrams.

I've seen photos of whiteboards, drawings in MS Paint, and other stuff. The tool rarely matters. What matters more is the content. A few tips for that:

Have clear meaning what a box means and what an arrow means. Don't make it inconsistent like "this box is a server, this box is a software component, and this box a message". If you need multiple types, then draw them differently (colors, rounded corners, dotted, etc).

One statement, one diagram. Don't make multiple statements in one diagram like "Here you see we send do more messages then necessary and you also see the undesirable coupling between Foo and Bar". Ok, there is also value in overview diagrams to show "everything" but those are for live use in discussions and not for documentation which should be understandable on its own.

[finder83]

Thanks!

[jugg1es]

draw.io (which is now app.diagrams.net) is all I've ever needed. I got my company to buy the Confluence plugin for it too. It's free to use by itself.