Home > On-Demand Archives > Q&A Sessions >

Live Q&A - Express Your Software Ideas Graphically

Jean Labrosse - Watch Now - EOC 2022 - Duration: 18:52

Live Q&A - Express Your Software Ideas Graphically
Jean Labrosse
Live Q&A with Jean Labrosse for the theatre talk titled Express Your Software Ideas Graphically
M↓ MARKDOWN HELP
italicssurround text with
*asterisks*
boldsurround text with
**two asterisks**
hyperlink
[hyperlink](https://example.com)
or just a bare URL
code
surround text with
`backticks`
strikethroughsurround text with
~~two tilde characters~~
quote
prefix with
>

bjuberchaub
Score: 0 | 2 years ago | no reply

Very relevant. What about UML? Diagrams are excellent, but even better if semantics are standardized. The Entity Relationship Diagram (ERD) is a lovely basis for a semantic model for implementation and analysis. Visual Paradigm may be an interesting tool as they support ERD and state models (including composite state models) across multiple platforms: https://www.visual-paradigm.com.

Thank you!

Aina
Score: 0 | 2 years ago | 1 reply

Thank you for the talk. I also use schematics a lot, especially finite state machines and UML's sequence diagrams, to explain complex interactions between modules.
A tool that I find interesting, as it is free and web-based (there is also a computer application): https://app.diagrams.net.
Hope this will be useful!

JeanLabrosseSpeaker
Score: 0 | 2 years ago | 1 reply

Interesting indeed. Has this been around for a long time? Are there regular updates? Hope it remains available for years to come.

Aina
Score: 0 | 2 years ago | no reply

I heard about this tool two years ago. As I am using web app, I do not know if there are frequent updates. I did not noticed any change so far, except the address (It was peviously named draw.io)

cghaba
Score: 0 | 2 years ago | 1 reply

Thank you for the talk. It was nice to see that you use/d some of the tools I also use/d. I am involved in both embedded systems and digital design (FPGA). If in the embedded world the graphic is used to complement the code design and for a better documentation, in digital design graphics are used more in the design process. I saw designing tools going from graphics (logic gate diagrams) to code (hardware description languages) but never dropping completely graphics. Even the newest tools make use of graphics to create high-level block diagrams that allow to have that 50000 feet view of the design, so for better understanding all the relationships between components and signals going in and out of them.
In old versions of Xilinx ISE tools there was a graphic tool named StateCAD used to draw FSMs from which your could automatically generate Verilog or VHDL code. I don't know why they dropped it.
I also use graphviz to draw FSMs or other diagrams that can be built with this tool. The reason is because I can generate the diagram from a text file that can be quickly written with any text editor and can also be easily modified or reused (which means an increased productivity) - drawing with the mouse is also possible, but it is much slower. As you said, a picture worth a thousand words but if you can draw it base on a few lines of code, it is even better.

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Thank you for attending and for sharing your thoughts. I'll check out GraphViz as it sounds like a neat tool.

vbravos
Score: 0 | 2 years ago | 1 reply

A good talk! Thanks!!

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Thank you for attending.

WilsonPardiJunior
Score: 0 | 2 years ago | 1 reply

Hi Jean Labrosse,

Thank as lot for your presentation. It was very insightful specially because you gave us a very broad overview of current tools that can help us in "visualize the software".

My "addendum" here is regarding the possibility of interacting visual descriptions of the source code using Doxygen as was discussed by you and some of other peers.
There is an interesting (but still very simple) extension to Doxygen called Moritz that generates Nassi-Shneiderman diagramms of functions and methods in a C/C++ source as html files, which could be included in a software documentation or just watched by using a browser:

https://sourceforge.net/projects/moritz/

In addition, something extremely useful would be a tool that could visualize not only classes, functions, objects, variables, etc but also the flow of data inside a large software application.. ;-)

Best Regards from sunny Japan,

Wilson

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Thanks, I?m sure others will also find this useful.

Steve_Wheeler
Score: 0 | 2 years ago | no reply

Good talk. I've used Vizio for memory maps and similar diagrams, but for documenting state machines, flow control, and communications links, I usually used graphviz. It's not hard to process a state machine implemented as a table to produce the necessary graphviz statements. Depending on the language, call dependency graphs are also not that hard to produce automatically.

leandropg
Score: 0 | 2 years ago | 1 reply

Thanks for all your advises. I liked the ISR and Task diagrams. I like document all, however sometimes there isn't time to make that. Additionally, I use doxygen (https://www.doxygen.nl/index.html) for obtain the documentation from the code.

JeanLabrosseSpeaker
Score: 0 | 2 years ago | 2 replies

Well, as far as I?m concerned, the diagrams don?t have to be pretty, hand drawn works fine if that?s something you can put together quickly.
I?ve used ?Doxygen? . It?s better than nothing but it still remains to be only text and it doesn?t give you a 50,000 foot level view.

OmerHeybeli
Score: 0 | 2 years ago | 1 reply

What is your suggestion about SW documentation? (Except Doxygen)
UML, is it suitable?

JeanLabrosseSpeaker
Score: 1 | 2 years ago | no reply

Well, Doxygen is fine especially to avoid having to duplicate the documentation of APIs. If you can add URLs to illustrations or further explanation of those APIs then it would augment the usefulness of the code's documentation. Of course, you would have to maintain the illustrations but at least they would be linked to the code.
A lot depends of what your code is used for and who the audience is. In my case, my 'product' was software modules so it was important for me to make sure users would have as much information about our products so they can make good decisions when using such software. If the documentation is for internal use or simply yourself, I'd say do as much as you believe you will need to be able to either understand it yourself down the road or, enough to be able to pass along to someone else. Of course, we are all subject to tight schedules and market pressures and unfortunately, 'documentation' is almost always the first to be thrown out the window.
I haven't used UML so I really cannot comment. All I can say is use whatever helps you or your team. If your team is trained in UML and they understand it then you use that. I look at this like coding standards, something is better than nothing!

leandropg
Score: 0 | 2 years ago | no reply

Of course Jean... I will work on that in my next project... Thanks

SeanStel
Score: 0 | 2 years ago | 1 reply

Jean,
Thank you for your talk. I make extensive use of diagrams in my design work, and also when deciphering legacy code. It was helpful to see how you do it, and I learned of some new types of diagrams and tools which I was not previously aware of.
Most of the diagram tools that you presented about have graphical point and click interfaces. Do you prefer this kind of interface over text based tools like plantuml?
Thanks,
Sean

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Sean, Yes, I prefer point and click interfaces. That being said, I?m not familiar with PlantUML ?
? Just looked at a couple of videos on YouTube. Quite cool, certainly another tool in one?s arsenal.

Erwin
Score: 1 | 2 years ago | 1 reply

Thank you very much it's always a pleasure to listen to your informative talks. I also think that it's the best approach for starting a development by drawing some "big picture" diagrams. Especially if you as as en embedded engineer are new to technical domain. These graphical approach is really helpful to close the gap between the domain experts (who know what to do) and the embedded developer (who knows how to implement it). At the very end you mentioned the problem of keeping source and documentation up to date. To me some "best practices" for this would be another interresting topic to hear about. As long as a project is in time this is nothing care about but when deadlines arrive i heard so many times "features are more important than documentation". And in the end if your product moves from development stage to life cycle mainainance you pay the price for this.

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Erwin,
Thanks for the feedback. I?ve mostly seen younger Engineers just wanting to go to code because that?s the fun part. I think the fun part is to ?see? a design without having code. The code, IMHO, is the easy part, once you understand the big picture. The less fun part is, to me, the debugging stage which a lot of that can be diminished using these techniques.
And your last comment, my answer is: ?There is never enough time to do it right, but you will be given the time to do it over!?

Thomas.Schaertel
Score: 0 | 2 years ago | 1 reply

I really enjoyed your talk as it was also very practical. In respect to the tools you used there is also need to update those regularly or convert the visual to a different format. Over the years lots of tools vanished or run only under old OSs. This adds additional amount of work for documentation. Thank you also for sharing the slides (which I wasn't aware of so I took handwritten notes). This was a great presentation which I liked very much. Thank you!

JeanLabrosseSpeaker
Score: 0 | 2 years ago | no reply

Thomas,
Thanks you for you comments. I agree that some of these tools go obsolete over the years. Hopefully, the longevity of the tools is more than the lifetime of the embedded product (which is not always the case). I used these tools to mostly help in the design and pass information to others that would inherit the software. My point is mostly to say that textual description or code itself is not very good at providing an overall 'picture' of an application, especially a complex one.
Glad you enjoyed the talk.
Jean

16:05:42	 From  Keith J : Jean - No question but thank you.  Very real and relatable. Another great presentation as usual although very different than your typical subject.
16:07:28	 From  Peter Schulz : I'm always disappointed by students not able to provide an introductionary block diagram in their theses. You read 10 pages of text without any picture. Hard to get into their solutions.
16:10:37	 From  CPannell : For UML-ish illustrations I vastly prefer using PlantUML to programmatically write the diagrams
16:10:55	 From  ofheybeli : would you recommend designing API with UML for a graphical diagram, sequence diagram, etc.?
16:10:56	 From  CPannell : just check it into your version control and modify as needed
16:11:49	 From  Gary Sutcliffe : I like yEd Graph Editor for flow charts and state machines. There are lots of alternatives as you pointed out.
16:13:52	 From  Jay Cosper : +1 for plantuml
16:16:33	 From  CPannell : iirc Doxygen or sphinx, I forget which can be configured to generate callgraphs, but not much better. You CAN link your diagrams into your doxygen docs so they will show up together
16:17:01	 From  Jay Cosper : Correct. We used Doxygen this way
16:18:03	 From  Andreas J. : draw.io would be another good one …
16:19:39	 From  ofheybeli : Would you suggest giving a version to the source code file? How do you think it would be to increase the version with each change?
16:19:59	 From  Andreas J. : thx for the tipps linking inside doxygen - Is doxygen flexible/easy to handle  enough to create a whole „master" document?
16:20:22	 From  CPannell : hooking sphinx into doxygen is nice enough for that
16:20:25	 From  Jay Cosper : thanks for the talk!
16:20:29	 From  CPannell : doxygen is a bit ugly and clunky on its own
16:20:33	 From  ofheybeli : tnaks
16:20:34	 From  Andreas J. : thx!
16:20:34	 From  CPannell : check Microsoft dev blog on it

OUR SPONSORS

OUR PARTNERS