Futilities/human/ui standards: Difference between revisions
< Futilities | human
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
| Line 10: | Line 10: | ||
** describe what is missing | ** describe what is missing | ||
* Error messages will be human-readable. | * Error messages will be human-readable. | ||
* If an operation might take a long time, there will be visual feedback regarding progress. | * If an operation might take a long time, there will be visual feedback regarding progress. | ||
** This feedback does not have to be quantitative or make any estimates about completion, but if possible it should provide enough information for the user to compare with other runs on similar data and make their own reasonable guess. | ** This feedback does not have to be quantitative or make any estimates about completion, but if possible it should provide enough information for the user to compare with other runs on similar data and make their own reasonable guess. | ||
** The application should not, by default, take extra time to gather information necessary for estimating percent-completion or time-to-complete. It may offer this service as a user option, however. | ** The application should not, by default, take extra time to gather information necessary for estimating percent-completion or time-to-complete. It may offer this service as a user option, however. | ||
If a machine-interface is desired (e.g. communicating with the app via JSON or XML), there will be an <code>--API</code> flag; when that flag is used, these guidelines do not apply. I have not had need to implement this yet, however. | |||
==Notes== | ==Notes== | ||
Handy command for making a commandlike link to a php executable: | Handy command for making a commandlike link to a php executable: | ||
ln -r --symbolic ./{{arg|X}}.php {{arg|X}} | ln -r --symbolic ./{{arg|X}}.php {{arg|X}} | ||
...where {{arg|X}} is the name of the executable php file (first line must be {{fmt/code|#!/usr/bin/php}}. and the file must have {{fmt/code|+x}} permission). | ...where {{arg|X}} is the name of the executable php file (first line must be {{fmt/code|#!/usr/bin/php}}. and the file must have {{fmt/code|+x}} permission). | ||
Revision as of 00:59, 10 September 2022
|
User Interface standards and conventions as used in The Futilities
|
Guidelines
- Commands will always identify themselves when run (name, version, date of last major revision).
- In general, the app should always guide the user towards constructing a useful command string.
- When a command is run without proper input (including no input), it should at least:
- describe itself (name, version, revision date)
- show the format it expects for input arguments
- list any available options
- link to a documentation page.
- describe what is missing
- Error messages will be human-readable.
- If an operation might take a long time, there will be visual feedback regarding progress.
- This feedback does not have to be quantitative or make any estimates about completion, but if possible it should provide enough information for the user to compare with other runs on similar data and make their own reasonable guess.
- The application should not, by default, take extra time to gather information necessary for estimating percent-completion or time-to-complete. It may offer this service as a user option, however.
If a machine-interface is desired (e.g. communicating with the app via JSON or XML), there will be an --API flag; when that flag is used, these guidelines do not apply. I have not had need to implement this yet, however.
Notes
Handy command for making a commandlike link to a php executable:
ln -r --symbolic ./<X>.php <X>
...where <X> is the name of the executable php file (first line must be «#!/usr/bin/php». and the file must have «+x» permission).