Fennec CLI and user interface are explictly and purposefully designed with user experience mandates. Each of them gone through thorough usability testing over time for growth and simplification.
Remember, the pain in developing
.gitlab-ci.yml inspired this project. Hence,
we should learn from the lesson: the very first thing to do is to design an
easy, intuitively understandable, and comprehesible way to deploy Fennec.
Mandate #1 - Keep Installation Simple
Installing Fennec as a local software should be as simple as:
$ sudo apt-get install fennec -y
By design, user should ONLY be instructed to install Fennec package ( not to confuse with packaging tasks) with 1-line command. That also means the command should setup everything including its dependencies.
- Have a clear autonomous, scriptable, controllable way to handle execution.
- Resolves all dependencies autonomously.
- Practices safe dependencies and parameters checking.
- Always do the right thing first; speed and scale comes later.
- Write a bunch of documents to let user to set things up in order to use. That’s developers’ job. Period.
- Do things without testing.
- Do things without having a mind how to fully control it.
- Hide expression and meaning. Just be open, direct, and straight already.
Mandate #2 - Easy One-line Repository Setup
Setting up repository with Fennec should be as simple as:
$ fennec --install
All settings, executions, scripts, recipes, and so on should be properly configured before deliver to any user.
- Organize, test, and comply to this rule.
- Keep all execution independent of yml script. Maintain semi-automatic principle.
- Do things that introduces more documentation addendum (we all hate that).
- Do anything that breaks this simple one-line instruction.
Mandate #3 - Simple Lines YAML Configuration Files
Fennec’s objective is to keep the repository’s
.gitlab-ci.yml clean and dead
simple. Hence, it should be as neat as:
include: - .fennec/core/linux/debian.yml - .fennec/test/linux/go.yml - .fennec/publish/hugo/debian.yml - .fennec/package/linux/go.yml - .fennec/upstream/linux/go.yml
- Keep executions inside your fennec execution scripts.
- Only let user to configure fennec via key variables.
- Create something and expect users to write the execution codes.
- Expect user to configure a lot of key variables (>8). That’s absurd.
- Expect user to read any Oxford’s English dictionary sized documentations.
Mandate #4 - Write A Human Readable Help
Fennec’s help prompt should be as simple as, as an example:
$ fennec --help Fennec Your repository's one-stop shop for GitLab CI YAML templates. ------------------------------------------------------------------------------- To use: ./fennec.sh [ACTION] [ARGUMENTS] ACTIONS 1. -h, --help print help. Longest help is up to this length for terminal friendly printout. 2. -v, --version print app version. 3. -i, --install install the fennec library inside this repository. Its default location is in the current directory. It optional value is given, it will only install that component. OPTIONAL VALUES: 1. -i fennec install the gitlab-ci fennec. OPTIONAL ARGUMENTS: 1. -p, --path [/path/to/repo] the path you wish to install fennec library. 4. -u, --uninstall uninstall the fennec library inside this repository. Its default location is in the current directory. If optional value is given, it will only uninstall that component. OPTIONAL VALUES: 1. -u fennec OPTIONAL ARGUMENTS: 1. -p, --path [/path/to/repo] the path you wish to install fennec library. 5. -U, --update update the fennec library inside this repository. Its default location is in the current directory. If optional value is given, it will only update that component. OPTIONAL VALUES: 1. -U fennec OPTIONAL ARGUMENTS: 1. -p, --path [/path/to/repo] the path you wish to update fennec library.
Write it clear explaination in the user interface, like 80 columns for terminal CLI. Make sure user can get all the necessary information for each actions.
- Write it clear with explaination, tells the required values for each arguments, relates the associated arguments to the action.
- Differenciate action and flags.
- Write example commands for each action.
- Write unless texts. That’s like giving a bottle of kerosine to a thirsty person. Please, respect people is looking for help.
- Disrespect user interface. Respect the interface boundaries.
- Write with assumptions. Don’t expect user to know everything. They use help for a reason.