11-05-2014 10:49 AM
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).
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
11-05-2014 11:19 AM
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.
11-05-2014 11:31 AM
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?
11-05-2014 11:38 AM
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.
11-05-2014 11:48 AM
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.
11-05-2014 11:51 AM
Yes...do show.
11-05-2014 11:58 AM
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...
11-06-2014 01:08 AM
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.
11-06-2014 10:50 AM
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...