One picture is worth of thousand words. So true. Even if you describe some flow with many detailed paragraphs one sequence diagram might show the idea instantly to the reader much better than all the words.
Separation of diagram drawing software (Visio, Dia, ...) from your main documentation system (Google Docs, Latex, doxygen, ...) is not a good idea. Having no access to source of the diagram makes modification much harder to do (when original author is not available, you have, actually, re-draw the diagram from scratch to fix some minor change).
Text-based diagrams and some form of post-processing is the answer to above problem. You embed your documentation AND the diagrams in the document and tools change those into graphics when needed. Example of such systems cooperation is doxygen and plantuml.
Let's see how easy sequence diagram could be expressed in plantuml:
@startuml{sequence.png} MainProcess -> Library: FacadeCall() Library -> SSO: GetToken() Library -> Server: CallService(token) Server -> SSO: IsTokenValid(token) @enduml
The result is rendered as diagram below:
There are more advanced functionality there, but I hope you have already caught the idea.
Next diagram type I'd like to explore is state diagram:
@startuml{state.png} [*] -right-> DoorOpened: Open DoorOpened -down-> DoorClosed: Close DoorClosed --> DoorOpened: Close DoorOpened --> WindowOpened: OpenWindow WindowOpened --> DoorOpened: CloseWindow DoorClosed --> DoorClosed: Close DoorOpened: lights_on DoorClosed: lights_off @enduml
The result looks like:
As you can see you can leave positioning to automatic algorithm or specify manually some directions quite easily.
And what about class diagram? Sure! No problem!
@startuml{class.png} class Student { Name } Student "0..*" -right- "1..*" Course (Student, Course) . Enrollment Student "0..*" -- "1..*" Class class Enrollment { drop() cancel() } @enduml
And the result:
Quite easy and intuitive!