How to meaningful document an actor design

Question

I'm pretty new to akka/actor systems and try to understand code which a colleague has written.
Doing this, I ask myself what kind of documentation would be helpful to get a faster understanding of the implemented "actor system".
As far as i understand so far, you need to understand at least two different perspective of the systems in order to understand it.

• The first is the static "creation hierarchy" which mainly defines the child-parent relationship between actors.
• The second is the dynamic "message/event flow" which mainly defines the exchanged messages between the actors. As a special case this one also includes realised finite state machines.
  

So, i wonder if there are common best practices on how to document an actor system:

• What kind of views should be documented?
• Are there recommended ways on how to structure the code (for instance reflecting the parent-child relation as package structure)?
• Naming conventions?
• Tools that are able to parse the code and provide some documentation?
• ...

Answer 1

As I'm yet unable to comment, I'd at least like to point you to akka-viz for the purpose of visualization.

I was also wondering recently about the package structure... and if one should somehow depict the actor hierarchy this way. I then went on and applied a DDD view where actors are nothing but services acting on entities. This doesn't put an emphasis on the implementation detail akka when trying to understand what the application does. The latter being what the package structure should enable people to do.

Would also be interested in a best practice though if there is one :)