Flowchart Documentation – Representing a User Event
diagramsdocumentationflowchart
I was wondering which symbol should be used for representing a user event (i.e. button click).
seems like it should suffice, but isn't a user click technically ?
Best Answer
Since this question remains unanswered, I'd like to expand on my comments.
In a flow chart, you probably don't need to represent events at the level of detail that you are thinking. A flow chart is a representation of a workflow, process, or algorithm. At the most basic level, it contains terminals (a start condition or event and one or more stop conditions or events), processes that cause data to change, decisions that need to be made, and input and output. There are some other concepts, such as referring to other processes (which may be documented in other flow charts), representing documents rather than just data, or manual operations that exist outside of the workflow or algorithm.
If you are modeling software, a button click is a very detailed event. If anything, the button click is most likely to be a terminal - the act of clicking a button starts a process. However, I wouldn't refer to this as a button click in a flow chart. This button click represents something at the process level - submitting data or forms, perhaps. That would be the true starting terminal. Alternatively, the entire process of a user completing a form could be represented as input - this would include every keystroke needed to complete the form as well as a button click or keystroke to submit it.
When you are creating flow charts, abstract away the user interface. Even abstract away the software. Think in terms of the data and information that you need and what high level events start the process. Put those onto the flow chart.
Personally, I tend to write all variable/function/class names, comments and documentation in English. And no, it's not my native language (Dutch is).
There are several reasons for this:
As others have said, English is the de facto lingua franca of programming. If you're working in an international team (with coworkers, foreign students/teachers, or other contributors to an open source project) it's usually the obvious choice, even if none of the people involved are native speakers.
Even for my personal projects that I haven't shared with anyone, I use English. You never know when you might want to distribute something (e.g. by turning it into an open source project, or just sending a copy to a friend).
This is especially the case if you might want to distribute the entire revision history by publishing it somewhere, since this way it's more useful without having to go back and translate everything.
Even for projects I have no intention of ever sharing with anyone, it's English all the way. Best to keep up the habit.
Much of programming and computer jargon is based on English. Even when talking to other native Dutch speakers about these topics, I tend to throw in a lot of English words and phrases. If your comments are going to contain English anyway, they might as well contain only English.
Dutch comments often just look wrong somehow. Out of context, maybe.
For non-programming related documentation (e.g. user docs) it really depends on the intended audience. There are definitely cases where providing documentation in non-English languages makes sense, but I think there are very few cases where not providing English documentation makes sense1. Yes, this means you may have to provide the same documentation translated into multiple languages.
1 Even if the product being documented is tightly bound to a geographical region where English is not one of the primary languages, that doesn't necessarily excuse a lack of English docs. For example, tax software for the Dutch market at first look wouldn't seem to need non-Dutch documentation. Until you consider foreigners living and working here, perhaps needing all the help they can get to figure out an unfamiliar tax system. And (western) foreigners living here are much more likely to know English than any other non-Dutch language -- though in this particular example Arabic and Turkish docs might be useful too due to relatively large immigrant communities from those regions.
I feel Message Sequence Chart/Sequence diagram is better suited for documenting RESTful API interaction. What you have is a state diagram, while RESTful API by definition is stateless.
Best Answer
Since this question remains unanswered, I'd like to expand on my comments.
In a flow chart, you probably don't need to represent events at the level of detail that you are thinking. A flow chart is a representation of a workflow, process, or algorithm. At the most basic level, it contains terminals (a start condition or event and one or more stop conditions or events), processes that cause data to change, decisions that need to be made, and input and output. There are some other concepts, such as referring to other processes (which may be documented in other flow charts), representing documents rather than just data, or manual operations that exist outside of the workflow or algorithm.
If you are modeling software, a button click is a very detailed event. If anything, the button click is most likely to be a terminal - the act of clicking a button starts a process. However, I wouldn't refer to this as a button click in a flow chart. This button click represents something at the process level - submitting data or forms, perhaps. That would be the true starting terminal. Alternatively, the entire process of a user completing a form could be represented as input - this would include every keystroke needed to complete the form as well as a button click or keystroke to submit it.
When you are creating flow charts, abstract away the user interface. Even abstract away the software. Think in terms of the data and information that you need and what high level events start the process. Put those onto the flow chart.