UI Analysis and Design Document
For an upgrade or rewrite of an existing application, especially a bigger one, we need to have a Design Document that describes User Interface.
The Design Document
User Interface consists of the variety of views and controls each with actions executed when user interacts with them. For example, a CRUD grid would display the grid view itself (one way communication from the app to user), then it can have paging toolbar with its buttons and inputs (two-way communication to and from the user who can initiate an action), the grid also needs some means (buttons) for adding and deleting records, it needs means for editing data (inline editing or an auxiliary form) and it may need Save and Reset buttons.
Such example grid could be displayed on the screen alone comprising the “view” or the “screen” as a whole, or it can be a part of a bigger layout, for example, it can be one tab of a tab panel, it can be in an item in HBox or VBox layout, etc.
The design document must provide a list and pictures of all screens with all items (buttons, fields, menus, controls, views) each screen consists of. It must also contain a screen (state) diagram depicting how user moves from screen to screen to execute the required tasks. And it contains description of the visual aspects of the application: font families, sizes and styles used, color theme, iconography, images, etc., especially when they differ from the default library themes.
Ideally, such document had existed for the original application now being upgraded before its actual coding commenced. Unfortunately, a design document is rarely available. Either it had not been written at all and the whole development had been based on conferencing between client and developers with no consistent written output or the changes, upgrades, refactoring rendered this document invalid and unusable.
One way or another, we still have the final result that the design document would describe if it existed or been up to date: the working application itself.
The task is to reverse engineer from the application to design document.
And the purpose is to have a solid basis for future development and estimates of effort and resources needed.
UI Analysis Howto
First and foremost, we must obtain an access to the application itself. It must be an unlimited access, for all roles, as we must not have some views hidden because they need an “admin” access rights to show up. Also, we need the app to run with a complete set of dummy data because we want to see views filled-in and we also need the freedom of adding, changing and deleting the application data while doing the analysis.
- Start with the home view or a dashboard. That is the screen that appears by default on the application start
- Give the screen a name and put it down to the screen diagram and the list. Ideally, we would take the name from the code if such exists and if we have the source code available.
- Write a brief description and purpose of the screen to the list. For example, purpose: to show and let the user to edit customers, description: grid with the list of customers, cell editing, paging toolbar and CRUD toolbar.
- Interact with a control (click, double-click, drag and drop) and for each of them write the control down and the action it does. For example, Save Button: Sends the new, changed and deleted records to the server.
- If the interaction shows a new screen (a window, new tab, or view) then put it down as described in point 2 and continue with the next control of the current view.
- Repeat points 4 and 5 for each and all controls on the screen.
- Take a view listed in point 5 that has not yet been analyzed and go to the point 2 until all you have processed all screens of the whole application.
Even if doing the best we can, there can still be some missing parts of the application, such as special error handling screens that do not pop up during the standard procedure above, or combination of data and action does not lead us through a branch of normal workflow. Therefore, we need to consult with the customer and solicit additional information needed to fully cover the app.
The special controls (user extensions) that are not part of the default Ext/Touch library require special attention because either they are not needed anymore and the current library already contains them in its core or they need to be upgraded what can take a considerable time and effort. Hence, collect all information available on the existing custom controls.
The result is a Design Document that contains all UI aspects of the application. It is in the form and scope suitable for commencing the development of the user interface, however, it cannot, and does not, cover special, behind-the-scene logic. For example, it would describe all fields, buttons, menus, grids and forms of Space Travel to Mars application but it would not contain the math necessary to calculate the trajectory.
Server side logic of data storage, update and retrieval and also the application logic executed by the server are also not part of the Design Document.
Well that’s not all, we’ve been doing only inventory, important, but nothing really creative yet. Now starts the real fun, but it is for another article.