Actor Framework Discussions

cancel
Showing results for 
Search instead for 
Did you mean: 

Documentation

Hello all,

I am currently working on a project for a client that is remote (as in, another country remote), and I have been struggling with the best ways to document a system that is dependent on the Actor Framework that goes beyond the traditional wordy functional description (i.e. something that might illustrate programatic flow or relations). 

  • There are class diagram that depict the relations between the classes, but this does not explain how classes interact and the number of classes might make the utility of this diagram questionable. 
  • We also have sequence diagrams, but, as the AF is asynchronous, it seems there are only two clearly defined points in the sequence - launch and stop.  Maybe this is the way to illustrate well defined events that occur as a response to some stimuli (i.e. user pushes button -> http request to change state of button ->  message fired from controller to button handler actor -> state of button handler actor changed)?

And there are a variety of other techniques that may or may not be suitable for documenting asynchronous systems.  But, my question is - what are people using for documenting there programs that would help customers actually understand what there system does and how it does it?

Cheers, Matt

0 Kudos
Message 1 of 9
(5,543 Views)

Short answer:  what do you do to document the interaction of queued message handlers?

My documentation tools didn't change much when I started using AF, because there isn't a lot of daylight between Af and QMH systems, conceptually (access to inheritance being the biggest difference).

I usually suppress the message classes in my class diagrams, and mark actors with an Actor stereotype.  This simplifies the diagram rather dramatically.

As for sequence diagrams, it's still useful (and valid) to show message traffic.  The sender process terminates as soon as the message is sent, of course, but the receiver may kick off additional messages to itself or other actors as a result.  So you wind up with a series of short interactions, rather than one long sequence.  And, as you've already identified, they are useful for showing the lfespan of more short-lived actors.

State diagrams can be helpful for showing the internal states of actors in response to messages.  This is especially true if the actor contains behavioral states.

Message 2 of 9
(3,785 Views)

niACS,

That is helpful, but I actually don't know much about documenting QMHs either. Could you please expand on that or provide some links to further reading?

Message 3 of 9
(3,785 Views)

I'm not sure I can, honestly.  I'm solidly in the "Code Is Truth" camp, which means I favor providing just enough documentation to satisfy the customer.  (Just enough can be quite a lot, if you do work for a medical device company or a national lab, but still...)

UML Distilled (Martin Fowler) is sitting on my desk.  It's a pretty succinct description of UML.

0 Kudos
Message 4 of 9
(3,785 Views)

Though now you have me thinking.

Would y'all find it useful to see a set of diagrams for a sample AF project, perhaps in a white paper?  I could probably put together a set for the Evaporative Cooler from the hands-on exercise.

Not, you know, today, but perhaps in the near future.

0 Kudos
Message 5 of 9
(3,785 Views)

Yes...do show.

0 Kudos
Message 6 of 9
(3,785 Views)

I think the only problem with the "Code Is Truth" view is that the AF is such a different paradigm, especially for those who might not be as familiar.  Since we ditch the whole follow the wire approach (in a big way) when we start developing a program consisting of a bunch of asynchronous tasks, the zeroth order question is - where does it all start? 

If you are unfamiliar with a program, you might be able to follow the programatic flow by following the wire, but now we need to communicate exactly how processes (and actors) are spawned and what is the chain of evenets/messages/commands that leads to the execution of a process.  Then, on top of this, we have to illustrate how that chain of events might affect the current state of the actor on which the process was initiated.  And finally, once we have explained individual events and processes, we need some way of stitching it all together to paint a cohesive picture of how the individual parts function to make the whole thing go.  Seems daunting at times for a larger application...

0 Kudos
Message 7 of 9
(3,785 Views)

niACS, please do that, it would be enormously helpful.

I document in the code itself, and in addition I have a word document for other developers that explain the flow (what launches what and when), the purpose of every module, documents methods to add more functionality as needed, and any points that I want to do in the future. It's shorter than it sounds, but still a lot of effort.

I also create sequence diagrams for common scenarios, but without message classes, only the actors. I don't document every possible scenario, though.

"Wisdom comes from experience. Experience is often a result of lack of wisdom.”
― Terry Pratchett
0 Kudos
Message 8 of 9
(3,785 Views)

One thing that I am running with currently is a spreadsheet that describes the message chains.  For instance, in the current application that I am developing, I may have a UI event that fires an http request which in turn causes a message to be sent to an actor which will then send a packaged command for execution down on a state machine in the actor core.  This might actually be more enlightening than a sequence diagram, but pictures always are nice...

0 Kudos
Message 9 of 9
(3,785 Views)