Visual language for documentation

[SeanFeldman]

We need a consistent "visual language" to describe concepts and elements for NServiceBus (endpoint, handler, saga, queue, command, event, etc). It would be good to have something similar to stencils/icons collection we could use in our documentation and presentations.

/cc @sergioc @dannycohen

[mauroservienti]

+1

[dannycohen]

As discussed with Sean - let's get the initial diagrams based on existing standards for depicting endpoints, messages and sagas etc. In the article's review we'll see what caveats we need to fill (with @sergioc's guidance)

[SimonCropp]

@SeanFeldman can u please point to some docs pages where you would see this as being useful

[SeanFeldman]

A few older ones:

• http://docs.particular.net/nservicebus/the-gateway-and-multi-site-distribution#cross-site-data-transfer
• http://docs.particular.net/nservicebus/load-balancing-with-the-distributor#routing-with-the-distributor
• http://docs.particular.net/nservicebus/introduction-to-the-gateway#what-are-logically-different-sites-
• http://docs.particular.net/nservicebus/introduction-to-the-gateway#using-the-gateway
• http://docs.particular.net/nservicebus/how-pub-sub-works

Newer ones:

• http://docs.particular.net/servicematrix/getting-started-sagasfullduplex-2.0

Coming soon:

• Azure scale out

[SimonCropp]

@SeanFeldman thanks

[dannycohen]

Also adding the visuals I've been using in various ppt's:

[sergioc]

Can you provide a full (or as complete as possible) list of all concepts/elements requiring ready-made visual components?

[dannycohen]

Can you provide a full (or as complete as possible) list of all concepts/elements requiring ready-made visual components?

• Endpoint
• Message (3 types)
• Command
• Event
• Timeout
• Service
• Hosting process
• Site
• Database

@SeanFeldman / @SimonCropp / @mauroservienti / All - anything I've missed ?

[SeanFeldman]

Additional candidates would be:

• Saga (long running process)
• Monitoring / stats / dashboard

[dannycohen]

Also see Distributor images added by @pablocastilla (currently in review) (PR)

[johnsimons]

So what are we waiting for to complete this ?

[sergioc]

Time.

Sergio

On Thu, Nov 27, 2014 at 7:27 AM, John Simons notifications@github.com wrote:

So what are we waiting for to complete this ?

— Reply to this email directly or view it on GitHub https://github.com/Particular/docs.particular.net/issues/421#issuecomment-64750918 .

[johnsimons]

Wouldn't these proposed stencils need to be created for tools like visio?

@sergioc yes we all lack time :wink:

@SeanFeldman as the author of this issue, can you keep on churning on this so it doesn't end up being forgotten ?

[SeanFeldman]

@johnsimons ok @sergioc Any ideas around timeline you're planing to look at it? Thanks :)

[SeanFeldman]

Throwing a few options out there

1. Each person creates a diagram and passes to @sergioc for "skinning".
2. Sergio comes up with "stencils" in something like https://www.lucidchart.com and we use those.

[sergioc]

@SeanFeldman Option 2 is best, possibly with addition of my time for revision for each diagram.

ETA potentially in 1 - 1,5 months.

[ramonsmits]

Another option is maybe to use an existing stencil template? If anybody has nice stencils to share then we only need to use them the same right? This could also help to convert such a stencil to a particular flavor by Sergio.

[sergioc]

@ramonsmits That's possible, but that stencil template would need to match the visual language we use in products.

[sergioc]

Here's an initial proposal. There's 2 sets of stencils, one has labeled stencils, the other doesn't.

I'll probably need to further refine the set (e.g. possibly with color) by working on an example application - maybe on one of the next documentation articles.

[SeanFeldman]

@sergioc a few questions as a result of looking on the stencils on the left only

1. Endpoint Rx vs Tx - could those be arrows indicating in vs out?
2. Timeout message - could it combine a message with something to indicate time (sand clock)?

[sergioc]

@SeanFeldman

1. Those endpoint icons are based on what we used in the products. Adding arrows would increase detail and make it more difficult to scale down the standard icon.
2. That's the standard icon we use in SI. But I'm intrigued by your suggestion - why a sand clock instead?

[SeanFeldman]

Sand clock has less details and you always know that time is running out, nothing else :)

[sergioc]

I do agree that the sand clock simplifies the visual!

I think the alarm clock better exemplifies time that "ran out", while sand clock better represents time that is "running out" - which concept applies best to represent a Timeout message - time that "ran out" or time that is "running out"?

Also note that the sand clock icon is a classic representation of "wait" - in the old progress/wait cursor indicator from Windows - not sure whether that could cause confusion.

Can someone else comment on @SeanFeldman's suggestion for a timeout icon?

[SeanFeldman]

Very good point on classical representation. There was a good post from Hanselman on this.

[SimonCropp]

Few questions

1. how will this be distributed to people? some custom visio stencil package? or leverage some online tool like https://www.lucidchart.com/ ?
2. When the stencils evolve how all the existing diagrams be updated?

[sergioc]

@SimonCropp

1. distribution yet to be decided - ideally use a collaborative platform (like LucidChart) that supports real stencils (with support for renaming labels, for example. I'll investigate further, but I'm betting on Lucid Chart ATM.
2. This can be approached in 3 ways:
   • Avoid changing existing stencils to minimise disruption
   • Whenever I update the stencils, I'll notify everyone in guidance (let me know if more needed) via email, to allow docs authors to see if existing diagrams need to be updated.
   • Lucid chart support dynamic image linking, i.e. you define an area of the diagram for exporting as an image, generate image URL, and whenever the diagram is updated, the linked image is updated automatically.

[SimonCropp]

@sergioc cool. glad you are thinking about it

[sergioc]

Here's a link to a Lucidchart document where you can find the stencils ready for copy-pasting: https://www.lucidchart.com/invitations/accept/a572c64e-3a6d-4aa7-8670-a94eec727d07

A couple of remarks: 1) If you want you can follow these instructions to have all shapes in a shape library. The only issue with this is that you have to manage that library whenever the stencils are updated. 2) When a shape is resized, the size of the labels is not adjusted. If needed I can supply an extra set of with a different size, though you can always control the final size of the diagram when exporting.

Let me know when you have a document created with theses shapes for me to check or if you need any help.

[SimonCropp]

so this seems to be done

[carlbm]

@sergioc Are these for public consumption? If so the lucidchart link has expired. It would be great to get hold of an updated copy.

[sergioc]

@carlbm we're not promoting the use of these stencils at the moment since they haven't been tested yet, but we won't prevent anyone from using. I've updated my previous comment with a valid share link.

In case you decide to use the stencils, we'd love to hear about any feedback or limitations found in your intended usage.

[carlbm]

Thank you. Some initial feedback (and I'm being very picky here, it's a great resource so thank you again!)

• Have a visio stencil to use out the box would be useful for those of us that use visio.
• Having a set with inverted colours would be useful for those of us who like light backgrounds (assuming this doesn't work against any of your guidelines.

[carlbm]

NSB.zip

I used your stencil to create a visio stencil which I've attached in case anyone else is interested. I haven't actually used it yet :smile: but I'll feedback once I have.

[sergioc]

@carlbm thanks. I assume you exported to Visio from LucidChart. That should cover the issue you mentioned above.

Having a set with inverted colours would be useful for those of us who like light backgrounds

The stencils were originally meant to be used on light backgrounds. Did you mean to say that you'd prefer a lighter stencil background to make the contrast between stencils and canvas less pronounced?