Technical Writing – VAED Method to Document a GUI Element
In database applications, CRUD is an important principle to observe. It is an acronym that stands for:
- Create (C) [i.e., connect to] database
- Read (R) database
- Use (U) data
- Destroy (D) [i.e., disconnect from] database
When documenting the features of a GUI (Graphic User Interface), there is a similar ACRONYM that can help you create CONSISTENT documentation, without leaving anything important out.
It is VAED.
- View (V) a GUI element.
- Add (A)
- Edit (E)
- Delete (D)
For example, let’s assume you are documenting a GUI field named Members.
Immediately create 4 different subject headings and then fill them in:
- To View a Subject
- To Add a Subject
- To Edit a Subject
- To Delete a Subject
Those 4 descriptions would cover everything that is related to that GUI element.
Usually, there is no separate “View [an Element]” section since such sections by default start off with a description of how you can view the element.
For example, a section on “Subjects” might start off with a HEADER 1 “Subjects” and then an introductory sentence:
“Select File > Subjects from the main menu to display the Subjects window.”
This might appropriately be followed by a screenshot of the Subjects window, with or without any legends. Make sure always follow a screenshot with a Figure Caption.
Then, you can follow this default “how to view” section with three explicit sections with their own HEADER 2 sub-headers:
- To Add a Subject
- To Edit a Subject
- To Delete a Subject
When you are done, the topic would be covered thoroughly.
In some sources you might see this acronym cited as VADE since it is easier to pronounce.
But I prefer VAED for a very simple reason: deletion in general is a risky and usually irreversible action that should always be described the last. If possible, I’d have a user Edit a GUI element before Deleting it.
