Who is the user, and how do we design for them?

[grahamc]

Last week I did an initial review of the Tinkerbell documentation. My experience had a few themes that seemed to repeat throughout. One of the strongest bits of feedback is the documentation and project needs to have a clear idea of:

• who is the project for
• what is their experience level
• what are they trying to do

Then, the documentation and tools can be built with this in mind. Tools can support imagined workflows. Documentation can cover topics the user should know but may not yet know.

My thinking is it is easier to get homelabbers up and going than move corporations over. Going to the cheap-and-cheerful deployments is easy. Selling big co's is trickier since the value proposition needs to be solid to get their sysops teams to shuffle out their old cobbler's shoes. I don't know, this isn't really my place to say. But the fact is that I don't know. We should know :).

This opens up a bunch of interesting questions, like:

• how much should the docs explain iPXE and netboot?
• if the user's goal is to install something to the hardware, is the quickstart doing its job?

At any rate, let me propose just one fundamental assumption I think we should make:

The user is probably comfortable on the CLI (#131)

The user will probably want to write some scripts to put some stuff together. We should support them and allow them to do this easily. However, the current tool doesn't get the job done yet. For example, here is a script I put together to create a template, delete all the existing workflows, and create a new one with the just-created template ID:

this rev / awk / rev stuff is to parse out the template ID from Created template: the-uuid:

docker exec -i deploy_tink-cli_1 tee "template.json" < ./my-template.json
template_id=$(docker exec -i deploy_tink-cli_1 tink template create -n "my-template" -p "template.json" \
  | rev | awk '{ print $1; }' | rev)

Then I delete all the workflows, where I have to parse out all the UUIDs from the ascii table:

for id in $(docker exec -i deploy_tink-cli_1 tink workflow list | cut -d' ' -f2  | grep -v  -- "-------------------" | grep -v WORKFLOW); do
  echo "Deleting workflow ID $id"
  docker exec -i deploy_tink-cli_1 tink workflow delete "$id"
done

Finally, I create a new workflow with the template ID I got earlier:

docker exec -i deploy_tink-cli_1 tink workflow create -t "$template_id" -r '{"device_1": "1c:34:da:5c:46:48"}'

To be clear, the ascii table is a nice UI affordance for humans on the terminal. However, while designing the features we implement we should consider who the is and what they will want to do.

In this case, what if instead the template creation command detected it was being piped, and just printed the ID? Or if the workflow list command had a --json flag? These simple changes make a big difference to the feeling of "can I use this for real?"

[gianarb]

Yep, I think the point I see the software being right now is: "it works if you know how to use it".
The next phase is: "let's make it usable by other people"

I think some issues are related to this topic:

• Provide release binary of tink CLI #73 as far as I like docker container, the idea to use them as a proxy to run a command line is unfriendly and it adds overhead on something that I am learning right now
• Reading hardware data from stdin #92 I do not feel the need for it to be honest but I think it stays in the area of: "make things friendly"

Just a tip, I will prefer to have a flag that is not a boolean --json. I prefer something like -o|--output=''|json|yaml, kubernetes also does something called -o wide that prints more information that just the std