Proposal for app embedded search documentation (DRAFT)
DRAFT PROPOSAL
Background
The issue of the behaviour of search boxes has been raised for discussion by the app interaction SIG several times, and it remains one of the priorities for the group. While it is the case that the overarching ask from users users is to have standardised behaviour in all search boxes across all FOLIO apps, it also needs to be acknowledged that this is not always desirable (some search boxes need to support specific behaviour that is not in line with the standard search behaviour) and not always possible to achieve within a reasonable timeframe given the available development resource.
Given these challenges, the app interaction SIG proposes that a good first step is to have standardised documentation for search behaviour easily available within each app. This proposal describes an approach to embedding such documentation in each app, and making it available through the app dropdown menus (alongside keyboard shortcuts documentation). While other approaches (such as adding this documentation to the documentation pages at https://docs.folio.org) , embedding the documentation into the app is preferred by the SIG because:
responsibility for documenting the behaviour lies with the development teams, as opposed to other groups - such as the documentation WG - having to determine the search behaviour after the fact
it is immediately available to users as they are using the app without having to dig into the full documentation
Embedding the search behaviour documentation in the app obviously does not preclude it from also being added to https://docs.folio.org if desired.
Proposal
The proposed approach is to have a new “Search behaviour” option in the dropdown menu next to the app name, containing a standardised list of headings.
The Behaviour headings proposed by the SIG are:
Default Search Fields - what fields does the default/main keyword search cover, and how does this search work?
Keyword Search Behavior - identifies the behavior of non-phrase searching
Phrase Search - can you do an exact phrase search?
Whitespace - how is whitespace handled? Are double spaces ignored, for example?
Wildcards - what wildcard characters, if any, are used, and how do they work?
Case Sensitivity - are searches case sensitive?
Anchoring/Truncation - Are searches left anchored? Do they include partial matching?
Punctuation/Diacritics - how are punctuation and diacritics handled? (Ignored?)
Stop Words - does searching make use of any stop words?
Escape Characters - are there any escape characters that allow you to search otherwise special characters, such as a wildcard character?
Standard descriptions could potentially also be provided describing the behaviour of the majority of apps.
The proposal is that this could be implemented as a centralised component in stripes-components allowing for easy and standardised adoption across apps. Where the apps follow the default search behaviour the work in the app would be minimal. However, where an app deviated from the default behaviour, the component could allow for specific descriptions or headings to be overridden while still using the common component - this would be similar to how standard keyboard shortcuts can be implemented in an app by importing importShortcuts from stripes-components , but the exact list of shortcuts to be imported can be specified and labels can be overridden using renameShortcutLabels.
After the stripes component is ready, it would be down to each app to implement the functionality as they are able to. For those apps following the standardised search behaviour this should be very straightforward with minimal effort. For those apps that deviate from the standardised search behaviour there would be more work involved, but this would be a healthy push to ensure that search behaviour was well understood for each app.
Issues
One major issue with this approach is that it assumes that each app will have a single search behaviour that can be documented. It is not clear what the correct approach would be in the case that different search boxes in a single app behaved differently to each other in terms of documented behaviour.
The single example of this identified to date is the Agreements app (for Trillium onwards) where an integrated search of an external search system (GOKB) means there are two search behaviour supported: Agreements app (when searching Agreements and the local KB) and GOKB (when searching GOKB).