How do you lay out your AF projects?

[BertMcMahan]

So I'm still getting into the AF and I'm loving it so far, but I'm having trouble with the initial phase of "Sketch out my actors and messages".

Some of the "Intro to AF" websites have some awesome looking charts they've made with sequences, message lists, that kind of thing. Right now I'm just using a piece of paper, which works but isn't flexible when I need to change things, and is super hard to document without just taking a picture of the paper.

What are the best practices for laying out and documenting your actor framework tree?

(I searched on this and found nothing, forgive me if this has been asked before!)

[Taggart]

Actor Tree diagrams work well for the static layout of the system, ie. who launches who and which actors can communicate directly with each other.

For help visualizing/planning sequences of messages I usually do the following:

1. I first layout an Activity Diagram for what I want to have happen (big picture).  It's kind of like a flowchart but it is good for showing parallel paths using forks and joins. Then I take each of the actions (or parallel paths) and think about which actor needs to be responsible for that.
2. Then I usually layout a sequence diagram which shows lifelines and the exact sequence of messages that implement the Activity Diagram.

That whole process is a lot of work, so I only do it if I really need to.   I don't do it for every set of messages, just for modelling high-level system type behavior.

If you need to brush up on your UML, checkout UML Distilled.

Hope that is helpful.

[Taggart]

Here are some examples.ActivityActor TreeSequence

[Taggart]

I should note that those are all drawn in Visio.  Usually, I lay them out by hand first to get them close since making lots of modifications in Visio is a pain.   Only the really important ones ever make it into Visio.  The other ones may get scanned and saved as pdfs.

I've also just drawn them on whiteboards and then snapped a picture with my phone.  

I've seen others draw them by hand using a stylus in something like Onenote.

[Oli_Wachno]

---

@Taggart wrote:

I should note that those are all drawn in Visio.  Usually, I lay them out by hand first to get them close since making lots of modifications in Visio is a pain.   Only the really important ones ever make it into Visio.  The other ones may get scanned and saved as pdfs.

I've also just drawn them on whiteboards and then snapped a picture with my phone.  

I've seen others draw them by hand using a stylus in something like Onenote.

---

I also prefer scribbling with a pencil on a piece of paper.

At least with me, it might be a matter of age

For customer documentation, you should have somthing nice and digital indeed.

[BertMcMahan]

Thanks Taggart, those are some good examples. Regarding your comment about UML, I've never used/learned it before. I've seen it mentioned a few times but haven't really looked into it enough to know what it brings to the table. Is it a modeling approach or some kind of common layout method?

[cbutcher]

UML is Unified Modeling Language, and gives/defines a standardised set of icons, glyphs and so on to convey information about the relationships between various things.

I recently found this link very helpful as an introduction to basic parts and a quick review if you're already familiar - UMLNotationSummary.pdf

As a further pointer, I've had a little bit of luck with yEd for simple diagrams (I don't know enough to produce complicated diagrams!) but it isn't the best tool. It is, however, free and cross platform (and also available in a web format, although I didn't find that very helpful)

[Taggart]

UML is just a standard that describes an "official" way to draw a set of software design documents.  It gives standard meaning to all the little symbols.

It's nice because it is language agnostic, so you can draw up a diagram of how something should act and then implement it in whatever programming language you want.  It's also nice because you can borrow programming designs from any other language.  If you read any programming textbooks you will probably see a lot of it.

There is also support for it in Visio and a lot of other drawing programs.

One way to get started is to look up and install the symbio goop toolkit. It might be called the NI GOOP toolkit now.  It's free.  Install it and it has a method to generate UML from your code.  

Here is a review of the book I recommended.  UML can be quite detailed and overwhelming, but the book does a good job of making it practical.  I recommend starting there.  If you google it, there is also a ton of online references for free, but I'm old-fashioned.  I prefer books.

[Taggart]

---

@Oli_Wachno wrote:

---

I also prefer scribbling with a pencil on a piece of paper.

At least with me, it might be a matter of age

For customer documentation, you should have somthing nice and digital indeed.

---

Agreed on both points.

[Eric.M]

It's quite funny that it's 2018, and it seems like the piece of paper and the whiteboard have not been obsoleted by tablets, leap motions and other geeky stuffs for this kind of tasks! ^^

As per my AF projects, it usually boils down to 3 main drawings:

- the "real-world" one - on paper : I enumerate classes, actors, interfaces. I also always draw a draft version of the UIs. I like picturing how I (and users) would interact with the final app early on in the design. It helps defining some actors. Also helps sorting out where to apply low/zero coupling. And it's super important as it gives an identity to your app.

- the OO step: UML. I've never created a complete UML diagram for one single project — with properties/methods— (never been asked/forced to) but I do put all my classes on the diagram and link them. It tremendously helps visualizing how entangled is your architecture. I use VioletUML editor. It's super simple (maybe too much), free, portable and there's even an online java applet.

- the workflow step: A flowchart or an AHT (acronym I've just come up with - Actor Hierarchy Tree). It can help managing actors lifetimes when necessary. Gives a rough idea of what runs at a given time. Violet can do both diagrams.