Application documentation
Forms and lists, in an application such as GG-CE, should have more documentation than only the labels. I think there are three levels of documentation that should be included:
-
High level documentation. This documentation should describe the main operations of the application. It should not enter in any specific user-interface or operative details, but link the general intent of users with the main sections of the application. In other words, it would be an explanation of what the left main menu of the application represents. (Inventory represents the germplasm material stored in the gene bank, the operations...) This documentation should be accessible application wide and served as independent web pages. At this level we might not need to reference any user interface elements.
-
Activity-related documentation. This documentation should show users how to perform specific tasks with the application. It should be a series of 1-2-3-... screens or pages that describe the steps needed to complete a task, which elements of the user interface should be used and how to complete each step. For instance if I want to do viability testing with a set of inventories step 1 would be to select the inventories that need to be tested, step 2 involves creating a "Viability test" action, etc. This should be an in-depth tutorial that explains which steps have to be completed in order to fulfil the requirements for the operation. The specific form documentation should be independent, reachable also by an info button on the form itself, so that if I am following a step-to-step tutorial, or if I am in the form and I have doubts on how it works, in both cases we can reach the same page.
-
Form specific documentation. This represents documentation to be displayed on the form itself. This is not a separate page, but information to be displayed directly next to the related control. There are several ways to provide such documentation: it could be a text area under the label of an input field, or a popup text area triggered when the user hovers over a control, or the actual content of the form. While the other types of documentation are provided in their own pages, this content should be linked with the labels and language translations currently in the JSON files. Ideally, forms should only show the labels and by pressing an info button activate the display of the documentation.
Let's take this form, for instance. Many of the labels apparently are self explanatory, but in reality they don't provide any indication about the format and content of the related control. For instance "Material or Method Used" may be crystal clear to the gene bank curator, but may be a mystery to the technician that has been tasked to fill the information. Latitude and Longitude seem obvious, but is it decimal degrees? Is it degrees-minutes and seconds? Is there a conversion utility? Uncertainty is numeric, but is it meters or not? We must assume a user that has one more level of ignorance.
We could include from the start the descriptions in the forms, but this will change the layout of all forms and eat up a lot of input space. We can use hovering to display documentation, but what about tablets?
With this ticket I would like to open a discussion to find the best way to organise documentation, both as an ideal user experience and an easy implementation for the development.