[toast0]

> The more appropriate idea is that you create documentation in the form of diagrams for free.

The problem is the diagrams are hard to create and hard to update and usually don't remain synchronized to the code. If there was a good way to create documents from the code (perhaps with some annotations required), it could just be a Make target and boom, free(ish) documentation.

[kgilpin]

I'm working on this, for Ruby, Python, and Java - https://appland.com/docs/get-started.html - would love to get your feedback.

[tonyarkles]

I’ve recently gotten reacquainted with Doxygen, and it allows you to embed PlantUML source right in your source code or Markdown files. Easy to write, easy to update, and stored as plaintext right in your source tree. I don’t love Doxygen, but it’s doing a great job at what I’m trying to do (document a complex C++ project)

[hack-shree]

What about org-mode? I am using plantUML in org-mode.

[tonyarkles]

I use PlantUML in org-mode as well! That's actually where I started, but found it much easier to recruit other people to write their own documentation (with sequence and state diagrams) by not requiring them to use Emacs :)