What is the way to visually outline application logic flow? - logic

We are looking for a way to visually describe to each other the logic flow of particular module or the application itself. I constantly stumble upon different block diagrams here and there, but still not sure if this is any kind of standard and has any particular name. What approach other teams or companies usually use in such cases?

You can create flow diagrams using Dia or Microsoft Visio. Dia is free though and quite decent
http://dia-installer.de/

UML contains some diagram types that matches what you seek.
http://en.wikipedia.org/wiki/Activity_diagram
http://en.wikipedia.org/wiki/Sequence_diagram
http://en.wikipedia.org/wiki/Unified_Modeling_Language

Related

How to design a software workflow chart? [closed]

Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I have been working for a while now but because of my earlier habits i never worked systematically.
I have never created a workflow chart for my software as how the software will work and instead of that i started working directly which in turn leads to many problems later.
Below is a small situation i currently need help with:-
NOTE:I have already created a software which does the following and i don't need any code for it, i just want to know how a workflow chart is created for such a situation.
1) Party List : This is where i would like to store all of the information of my customer.
2) Sales : Here i will sell my products to the customer.
There are 2 cases here, whenever the customer arrives we have an option to
either save it in the party list and select it from the list in the sales form
or type it manually and then save it
Now comes the checking part:-
If an entry was saved in Sales when the checkbox was ticked and the user selected a party, lets say "Akhmed" has been saved AND the user tries to delete the record of "Akhmed" from the Party List form then the software shouldn't allow it to do so as the entry of "Akhmed" already exist in Sales.
Can anyone show me how a workflow chart is created for such a situation?
EDIT
Here is a sample workflow i have made after reading some articles, please point out any improvements that can be made to it or is it completely wrong or anything.
First of all, great question. I wish all software engineers thought first before jumping to writing a code. Especially when it's about anything more serious than a couple of lines for fun.
I think your software flow can be expressed as Activity diagram. An example of activity diagram is expressed on this picture: https://www.tutorialspoint.com/uml/images/uml_activity_diagram.jpg
Basically, activity diagram is a combination of steps and transitions (arrows) connecting them. Step can be just something that happens in the flow, or it can be a logical operator (decision) which branches the flow execution into different directions.
If you need to also emphasize who needs to execute the step, besides just showing what the steps are, you can add swimlanes (horizontal or vertical columns showing the actor names) to the activity diagram. That's where it turns into a Flow Chart diagram. e.g. on this image you can see horizontal swimplanes explaining who does the step execution http://static1.creately.com/blog/wp-content/uploads/2011/11/Support-Process-Flowchart-Template-1024x613.png
Note that terminology can differ from person to person, but these are the names for these 2 kinds of diagrams I have mostly heard and used myself.
There are other kinds of diagrams too, but I think your specific case will be covered with the ones mentioned above. Although... use case diagram can be something you may be interested in, but that does not depict steps. That only will mention actors and what kind of actions they can do with your system. e.g. https://sourcemaking.com/files/sm/images/uml/img_32.jpg
You didn't ask for tools, but I usually prefer to use tools that are rigor (rather than loose like Visio), so I would recommend to use WhiteStarUML. It's free and does a great job. But as I said, it's strictly UML-based, so will require some familiarity with UML.
Finally, about your attached picture:
What you showed looks like an activity diagram with some illegal components on it (illegal from UML specification standpoint). Is it good or bad? - depends. If it's supposed to be a rigor UML diagram then it's bad. If it's just a sketch of an idea - not bad.
Your diagram mentions database sign (called "DB") and arrows connecting to it. That's illegal on an activity diagram UML. Instead, you can have a step which says "Data gets saved to Database", and remove the "DB". Also, you have a single step which says both "Party" and "Sales" on it - that's not a legal UML. I think you tried to express that there are 2 flows. In that case, just have 2 different activity diagrams instead of one.
Your question is quite broad but I'll give it a shot.
I think you want to reconsider your approach. I would suggest reading up on UML sequence diagrams. They are a kind of diagram that provides a way to represent how requests are made within code. UML, in general, can also be used to make class diagrams and other useful flow-like charts for representing code. Many tools, such as visual-paradigm, allow you to build UML diagrams (ex. class diagrams)that can be converted directly into code. This can be useful when getting you started on the program. There is a learning curve with using these tools as different kinds of arrows mean different things, but they can be very powerful. they can also be used to take existing code and convert it to a diagram, which is great when trying to explain how your program works.
here are some other links that might be useful:
lucidchart has an example of a pop-up window diagram like the one you described.
draw.io just allows for you to make the diagrams, not convert them to code, but it is an easy to use tool and integrates with google drive and git hub.
stackoverflow has some info on UML too.
If you are looking for a "professional workflow diagram" UML if a fine way to go, there are many ways they can be laid out and they can be quite professional, I learned about them in school and have used them at work to help plan out the flow of data through our system. There are many more UML tools out there, it might be worth looking into a tutorial to find what's best for you.
You seem to be on the right track, I have never added a database to my flow-charts but it is up to you on how detailed you want to get. You seem to be using the correct symbols!
Here is an awesome, free website that I use. https://www.draw.io/ it was created for making flow charts and other things.
I personally would remove the UI at the beginning of your chart. Try to stay away from the overly technical examples when starting out with flow-charts, hit up YouTube or Google images for some simple, but correct examples.
Good luck friend!

Stories and Scenarios that implies UI

I am trying to learn how to use BDD for our development process and I sometimes end-up writing things that implies a UI design, so for brand new development or new features, the UI does not always exists.
For example, if I say this in a scenario "When a column header is clicked" it implies that this feature is based on some sort of table or grid, but at this point we are still just writing user-stories so there is no UI yet.
That gets me confused to know at what point in the process do we come up with a UI design ?
Keep in mind, I only have read articles about BDD and I think it would help our team a lot but still very new at this! Thx!
If you write your scenarios with a focus on the capabilities of the system, you'll be able to refactor the underlying steps within those scenarios more easily. It keeps them flexible. So I'd ask - what does clicking the column get for you? Are you selecting something? What are you going to do with the selection? Are you searching for something and sorting by a value?
I like to see scenarios which say things like:
When I look for the entry
When I go to the diary for January
When I look at the newest entries
When I look at the same T-shirt in black
These could all involve clicking on a column header, but the implementation detail doesn't matter. It's the capability of the system.
Beneath these high-level scenarios and steps I like to create a screen or page with the smaller steps like clicking buttons in it. This makes it easy to refactor.
I wrote this in a DSL rather than English, but it works with the same idea - you can't tell from the steps whether it's a GUI or a web page, and some of the steps involve multiple UI actions:
http://code.google.com/p/wipflash/source/browse/Example.PetShop.Scenarios/PetRegistrationAndPurchase.cs
Hope you find it interesting and maybe it helps. Good luck!
I guess you can write around that by saying "when I sort the information by X, then..." But then you would have to adjust your scenario to remove any mention of the data being displayed in a grid format, which could lead to some rather obtuse writing.
I think it's a good idea to start with UI design as soon as you possibly can. In the case you mentioned above, I think it would be perfectly valid to augment the user story with sketch of the relevant UI as you would imagine it, and then refine it as you go along. A pencil sketch on a piece of paper should be fine. Or you could use a tablet and SketchBook Pro if you want something all digital.
My point is that I don't see a real reason for the UI design to be left out of user stories. You probably already know that you're going to build a Windows, WPF, or Web application. And it's safe to assume that when you want to display tabular data, you'll be using a grid. Keeping these assumptions out of the requirements obfuscates them without adding any real value.
User stories benefit from the fact, that you describe concrete interactions and once you know concrete data and behaviour of the system for it, you might as well add more information about the way you interact. This allows you to use some tools like Cucumber, which with Selenium enables you to translate a story to a test. You might go even further and e.g. for web apps capture all pages you start concrete story at and collect all interactions with that page resulting in some sort of information architecture you might use for documentation or prototyping and later UI testing.
On the other hand, this makes your stories somewhat brittle when it comes to UI changes. I think the agile way of thinking about this is same as when it comes to design changes - do not design for the future, do the simplest possible thing, in the future you might need to change it anyway.
If you stripped your user stories of all concrete things (even inputs) you will end up with use cases(at least in their simplest format, depends on how you write your stories). Use cases are in this respect not brittle at all, they specify only goals. This makes them resistant to change, but its harder to transfer information automatically using tools.
As for the process, RUP/UP derives UI from use cases, but I think agile is in its nature incremental (I will not say iterative, this would exclude agile methods like FDD and Kanban). This means, as you implement new story, you add to your UI what is necessary. This only makes adding UI specifics in stories more reasonable. The problem is, that this is not a very good way to create UI or more generally UX(user experience). This is exactly what one might call a weakpoint of agile. The Agile manifesto concentrates on functional software, but that is it. There are as far as I know no agile techniques for designing UI or UX.
I think you just need to step back a bit.
BAD: When I click the column header, the rows get sorted by the column I clicked.
GOOD: Then I sort the rows by name, or sometimes by ZIP code if the name is very common, like "Smith".
A user story / workflow is a sequence of what the user wants to achieve, not a sequence of actions how he achieves that. You are collecting the What's so you can determine the best How's for all users and use cases.
Looking at a singular aspect of your post:
if I say this in a scenario "When a column header is clicked" it implies that this feature is based on some sort of table or grid, but at this point we are still just writing user-stories so there is no UI yet.
If this came from a user, not from you, it would show a hidden expectation that there actually is a table or grid with column headers. Even coming from you it's not entirely without value, as you might be a user, too. It might be short-sighted, thinking of a grid just because it comes from an SQL query, or it might be spot-on because it's the presentation you expect the data in. A creative UI isnÄt a bad thing as such, but ignoring user expectations is.

Web Design: When (not) to use a Wizard

My boss believes that wizards make things simple for the user.
I think they have their place but I can't really define what that place is.
I feel there is a danger in turning something into steps that doesn't need them.
Does anyone know where I could find rules for such things, or even a guideline to follow that describes when and when not to use wizards and possibly even other UI elements.
Here is what some common Human Interface Guidelines have to say about when to use them. Most are quite restrictive:
Gnome HIG
An assistant is a secondary window that guides the user through an operation by breaking it into sequential steps. Assistants are useful for making complex operations less intimidating, as they restrict the information visible to the user at any given moment.
[...]
Assistants do have major downsides. After using an assistant it is often hard to figure out where the individual settings aggregated into the assistant are stored. Often people will resort to re-running the assistant, re-entering many settings that they don't want to change.
Assistants are often used in situations where a better solution would be to simplify, or even better automate, the process. Before using an assistant to step people through a complex operation, consider if the operation can be fundamentally simplified so an assistant is unnecessary.
Microsoft Windows Experience Interaction Guidelines:
Consider lightweight alternatives first, such as dialog boxes, task panes, or single pages. Wizards are a heavy UI, best used for multi-step, infrequently performed task. You don't have to use wizards—you can provide helpful information and assistance in any UI.
Apple Human Interface Guidelines
For products with complex setup procedures, a setup assistant can be helpful
(Assistants are not mentioned in any other context, as in the other HIG:s, so I assume that means that Apple think they have no place except for setup)
I'd agree with you that Wizards have their place. And that place is back in Azeroth.
No, but seriously, if the user has to input a lot of different data fields, using a Wizard to split up the data entry into several related groups might help to make things less confusing.
If the Wizard covers a process that consists of steps A, B, and C, and the input at B or C depends on the input at the previous step(s), a Wizard would probably be a good way to structure your application.
There are probably a lot of other situations in which using a Wizard would be warranted (those are just two off the top of my head), but in each case, you'd want to evaluate it and make sure that a Wizard is the absolute best option. To borrow an old saying, everything doesn't become a nail just because your boss wants you to use Wizards as a hammer. If that makes sense.
As far as best practices guidelines goes -- the use of Wizards seems to fall under UX rather than UI, but here's a few items that I came across:
Wizard-style forms best practices
Designing Effective Wizards: A Multidisciplinary Approach (Book)
Best Practice: Designing Wizards
Try reading this.
I would suggest to avoid wizards as much as possible. People have a short attention span and you risk that, at the middle of it, they start forgetting what the said, what they are doing there, etc.
That being said, i think that it may be viable when performing some shopping (e.g., checkout), first-time configurations, others?
When to Develop a Wizard
Always try to:
Only ask the information really needed
Simplify as much as you can, thus avoiding the need to additional explanation
When creating a wizard:
Clearly show the how many steps are needed and how many are completed
Allow the user to revert or cancel it

Generating UI from DB - the good, the bad and the ugly?

I've read a statement somewhere that generating UI automatically from DB layout (or business objects, or whatever other business layer) is a bad idea. I can also imagine a few good challenges that one would have to face in order to make something like this.
However I have not seen (nor could find) any examples of people attempting it. Thus I'm wondering - is it really that bad? It's definately not easy, but can it be done with any measure success? What are the major obstacles? It would be great to see some examples of successes and failures.
To clarify - with "generating UI automatically" I mean that the all forms with all their controls are generated completely automatically (at runtime or compile time), based perhaps on some hints in metadata on how the data should be represented. This is in contrast to designing forms by hand (as most people do).
Added: Found this somewhat related question
Added 2: OK, it seems that one way this can get pretty fair results is if enough presentation-related metadata is available. For this approach, how much would be "enough", and would it be any less work than designing the form manually? Does it also provide greater flexibility for future changes?
We had a project which would generate the database tables/stored proc as well as the UI from business classes. It was done in .NET and we used a lot of Custom Attributes on the classes and properties to make it behave how we wanted it to. It worked great though and if you manage to follow your design you can create customizations of your software really easily. We also did have a way of putting in "custom" user controls for some very exceptional cases.
All in all it worked out well for us. Unfortunately it is a sold banking product and there is no available source.
it's ok for something tiny where all you need is a utilitarian method to get the data in.
for anything resembling a real application though, it's a terrible idea. what makes for a good UI is the humanisation factor, the bits you tweak to ensure that this machine reacts well to a person's touch.
you just can't get that when your interface is generated mechanically.... well maybe with something approaching AI. :)
edit - to clarify: UI generated from code/db is fine as a starting point, it's just a rubbish end point.
hey this is not difficult to achieve at all and its not a bad idea at all. it all depends on your project needs. a lot of software products (mind you not projects but products) depend upon this model - so they dont have to rewrite their code / ui logic for different client needs. clients can customize their ui the way they want to using a designer form in the admin system
i have used xml for preserving meta data for this sort of stuff. some of the attributes which i saved for every field were:
friendlyname (label caption)
haspredefinedvalues (yes for drop
down list / multi check box list)
multiselect (if yes then check box
list, if no then drop down list)
datatype
maxlength
required
minvalue
maxvalue
regularexpression
enabled (to show or not to show)
sortkey (order on the web form)
regarding positioning - i did not care much and simply generate table tr td tags 1 below the other - however if you want to implement this as well, you can have 1 more attribute called CssClass where you can define ui specific properties (look and feel, positioning, etc) here
UPDATE: also note a lot of ecommerce products follow this kind of dynamic ui when you want to enter product information - as their clients can be selling everything under the sun from furniture to sex toys ;-) so instead of rewriting their code for every different industry they simply let their clients enter meta data for product attributes via an admin form :-)
i would also recommend you to look at Entity-attribute-value model - it has its own pros and cons but i feel it can be used quite well with your requirements.
In my Opinion there some things you should think about:
Does the customer need a function to customize his UI?
Are there a lot of different attributes or elements?
Is the effort of creating such an "rendering engine" worth it?
Okay, i think that its pretty obvious why you should think about these. It really depends on your project if that kind of model makes sense...
If you want to create some a lot of forms that can be customized at runtime then this model could be pretty uselful. Also, if you need to do a lot of smaller tools and you use this as some kind of "engine" then this effort could be worth it because you can save a lot of time.
With that kind of "rendering engine" you could automatically add error reportings, check the values or add other things that are always build up with the same pattern. But if you have too many of this things, elements or attributes then the performance can go down rapidly.
Another things that becomes interesting in bigger projects is, that changes that have to occur in each form just have to be made in the engine, not in each form. This could save A LOT of time if there is a bug in the finished application.
In our company we use a similar model for an interface generator between cash-software (right now i cant remember the right word for it...) and our application, just that it doesnt create an UI, but an output file for one of the applications.
We use XML to define the structure and how the values need to be converted and so on..
I would say that in most cases the data is not suitable for UI generation. That's why you almost always put a a layer of logic in between to interpret the DB information to the user. Another thing is that when you generate the UI from DB you will end up displaying the inner workings of the system, something that you normally don't want to do.
But it depends on where the DB came from. If it was created to exactly reflect what the users goals of the system is. If the users mental model of what the application should help them with is stored in the DB. Then it might just work. But then you have to start at the users end. If not I suggest you don't go that way.
Can you look on your problem from application architecture perspective? I see you as another database terrorist – trying to solve all by writing stored procedures. Why having UI at all? Try do it in DB script. In effect of such approach – on what composite system you will end up? When system serves different businesses – try modularization, selectively discovered components, restrict sharing references. UI shall be replaceable, independent from business layer. When storing so much data in DB – there is hard dependency of UI – system becomes monolith. How you implement MVVM pattern in scenario when UI is generated? Designers like Blend are containing lots of features, which cannot be replaced by most futuristic UI generator – unless – your development platform is Notepad only.
There is a hybrid approach where forms and all are described in a database to ensure consistency server side, which is then compiled to ensure efficiency client side on deploy.
A real-life example is the enterprise software MS Dynamics AX.
It has a 'Data' database and a 'Model' database.
The 'Model' stores forms, classes, jobs and every artefact the application needs to run.
Deploying the new software structure used to be to dump the model database and initiate a CIL compile (CIL for common intermediate language, something used by Microsoft in .net)
This way is suitable for enterprise-wide software and can handle large customizations. But keep in mind that this approach sets a framework that should be well understood by whoever gonna maintain and customize the application later.
I did this (in PHP / MySQL) to automatically generate sections of a CMS that I was building for a client. It worked OK my main problem was that the code that generates the forms became very opaque and difficult to understand therefore difficult to reuse and modify so I did not reuse it.
Note that the tables followed strict conventions such as naming, etc. which made it possible for the UI to expect particular columns and infer information about the naming of the columns and tables. There is a need for meta information to help the UI display the data.
Generally it can work however the thing is if your UI just mirrors the database then maybe there is lots of room to improve. A good UI should do much more than mirror a database, it should be built around human interaction patterns and preferences, not around the database structure.
So basically if you want to be cheap and do a quick-and-dirty interface which mirrors your DB then go for it. The main challenge would be to find good quality code that can do this or write it yourself.
From my perspective, it was always a problem to change edit forms when a very simple change was needed in a table structure.
I always had the feeling we have to spend too much time on rewriting the CRUD forms instead of developing the useful stuff, like processing / reporting / analyzing data, giving alerts for decisions etc...
For this reason, I made long time ago a code generator. So, it become easier to re-generate the forms with a simple restriction: to keep the CSS classes names. Simply like this!
UI was always based on a very "standard" code, controlled by a custom CSS.
Whenever I needed to change database structure, so update an edit form, I had to re-generate the code and redeploy.
One disadvantage I noticed was about the changes (customizations, improvements etc.) done on the previous generated code, which are lost when you re-generate it.
But anyway, the advantage of having a lot of work done by the code-generator was great!
I initially did it for the 2000s Microsoft ASP (Active Server Pages) & Microsoft SQL Server... so, when that technology was replaced by .NET, my code-generator become obsoleted.
I made something similar for PHP but I never finished it...
Anyway, from small experiments I found that generating code ON THE FLY can be way more helpful (and this approach does not exclude the SAVED generated code): no worries about changing database etc.
So, the next step was to create something that I am very proud to show here, and I think it is one nice resolution for the issue raised in this thread.
I would start with applicable use cases: https://data-seed.tech/usecases.php.
I worked to add details on how to use, but if something is still missing please let me know here!
You can change database structure, and with no line of code you can start edit data, and more like this, you have available an API for CRUD operations.
I am still a fan of the "code-generator" approach, and I think it is just a flavor of using XML/XSLT that I used for DATA-SEED. I plan to add code-generator functionalities.

Code Generator vs Code Refactoring

How do you like your CRUD programs. Code-generated, framework-driven, or manually written?
My experience with code generators is that they're a good start but after the changes have settled down I usually want to rewrite the modules by hand. Of course, that can become a maintenance problem. But it really turns into a "how long is a piece of rope" question. Which generators, frameworks, and resources are you dealing with? Some of them are horrors to deal with, others work all right.
I like code generators with custom templates for the following reasons:
Reduces coding effort
Easy to make global changes
Embed architecture in templates ensures developer compliance.
Less chance of coding errors.
Consistent functionality
Less to test.
In fact, using code generators I was able to create, or recreate, the store procedures, entity classes, and DAL from a modified database with 60+ tables in minutes when the schema was updated. By using custom templates, I was ensured that the all layers worked with my naming rules and ensured proper error handling and prevention of double insertion.
Great for fixed price contracts. If it is hourly, then you might want to do it by hand :-)
I like a mixture of framework driven and manually written. I've done a little bit with NHibernate and LinqtoSql and sometimes the queries they generate for me need a little bit of help.
This really depends on the size of your application. Hand-crafted Data Access Layers make the most sense for a very small application as you have ultimate control but for any medium to large size application I would recommend a code generator. I've had various experience with APEX SQL (not great), LINQ and Subsonic (both very good). I'm just about to evaluate a Telerik ORM shortly but I imagine that will be pretty good also.
If you use .Net use Linq, then it is easy to maintain. LinqToSql makes it easy to update your data model with out having to change the code a whole lot.
In my opinion code generators are a sign of bad design and violate DRY. Where as a good framework will have you maintaining less code. With frameworks you also end up extending and refactoring code rather than a code template.
Frameworks are choice one, if I need to use a code generator I like to throw together a quick Perl script that generates the code so I understand exactly what is getting generated and why.
They are useful if you view your users as data entry clerks to maintain your database tables for you. They help minimize the programming time required to meet minimum requirements.
If you want the quality of your work to reflect something better than that, the best that can be said for them is they might give you a jumpstart if you're not too sure how to do simple consistent UI screens yourself.
Personally I find that refactoring them into something useful and attractive based on real Use Cases takes longer than doing it from scratch. They're the kind of technique Dilbert's pointy-haired boss would love.
I find a good framework for CRUD logic better than code generators. I have run into situations when a complex set of tables generated a terribly slow query to produce the result.

Resources