How to document GUI screens transitions of a complex application

Question

There is an application based on multiple screen model with pretty complex net of transitions between these screens.

It has some similarities to a web page or Football Manager like games. Its main properties are:

• It has screen stack and it has back/history like function.
• Events cause screen transitions.
• Some of screens can work in different contexts (the source screen and external conditions influence what transitions are possible).
• Loops are possible

Due to a lack of better idea I have started with a state diagram and PlantUML and it worked good until the scale started to become a problem. In the mean time I catched many bugs very often related to screen transitions. The application development is probably already suffering from this complexity and lack of this kind of documentation.

After two weeks of pretty intensive analysis and map drawing the map is totally in progress and it becomes harder and harder to maintain it even when I have a fresh knowledge about it.

What approach should I adopt to produce a useful GUI map of this application? How do people manage such things in a time efficient way?

Answer 1

What approach should I adopt to produce a useful GUI map of this application? How do people manage such things in a time efficient way?

Quick Short Answer

State Transitions Charts are a good idea.

Represent each different screen as a single transition, very general, not too much detail, first. Add detail later.

Long Boring Extended Answer

I have work in several applications, similar to your use case.

And, configuration or setup "wizards", are a good example.

Like many developers, I ended using a state transition approach like you.

Remember U.M.L. is not the only way to model State Transitions, altought is a very good tool, and is today's standard

Sometimes, using a square with a label indicating some screen, for each screen, and arrow with labels indicating parameters that indicate transitions are enough.

As, I previously mention, State Diagrams are OK.

I read your question, and several stuff got my attention.

[1] Not sure, but, I think you are modeling screen too much detailed, model each screen very generic, first. You may add more detailed specifications, later.

[2] As you mention, you are using the same screen several times, with several parameters, as if it was a different screen or object.

Is not a bad idea, but, you could also get confused with too many settings.

Model each screen instance or ocurrence, as a different screen, with generic properties first.

[3] Are you using the right tool for modeling ?

A lot of people, on this UML days, jump straight to use software.

Many developers, start with a chalk-blackboard, or a marker-whiteboard, and, later, use some software, for modeling.

I have tried several software, both commercial, and open source.

For many reasons, I ended, using OpenOffice / LibreOffice Draw application.

Many UML software sometimes, have a lot of features on some modules, and lack others.

You are using a tool to compile a programming language into a diagram. Not bad idea, for small projects.

But, for very large projects, your mind may be doing extra work, and making you harder to think.

I suggest to switch to do visual diagrams or chart, directly, maybe with a whiteboard, a notebook, or a visual designer, like Umbrello, Libre Office Draw, or others.