Clarification on host file

[troppens]

The current README reads: "Define GPFS nodes in the hosts file in the following format."

"host file" is Ansible jargon. We cannot assume that readers of the README are familar with Ansible. Therefore I would recommend to say something like: "Define GPFS nodes in the Ansible inventory file (e.g. "./hosts") in the following format."

BTW, not sure, if we want to say "Spectrum Scale nodes" instead of "GPFS nodes", but this is a different discussion.

[whowutwut]

I totally agree with this comment @troppens .... 👏 thank you for opening it.

I think we have to differentiate concepts of Spectrum Scale and concept of Ansible. I'm not 100% sure yet how to best do this. The concept of Spectrum Scale is a clustering one, and I don't think we can just assign groups of nodes into Spectrum Scale concepts to the playbook "roles".... so that we could run against a "role"... like [nsd] or [gui]... some thought needs to be applied here.

[troppens]

That is a good question how to separate managed entities. Regarding Spectrum Scale I am thinking in layers:

Node => Cluster => NSD => Filesystem

A node can be a quorum node, but it is relevant on the cluster level, because a reboot of a quorum node could have impact to the whole cluster.

Not sure whether it is feasible to reflect this layering in Ansible roles or not. Also not clear to me how to mix in features such as GUI or CES, for instance.

[acch]

I agree that "hosts file" is not a term that's widely used. The Ansible documentation refers to "inventory" (link). We should keep documentation consistent with terminology in the official docs. I've tried to improve the README here — what do you think?

On another note, I'm not sure I agree with this:

We cannot assume that readers of the README are familar with Ansible.

Users must have a basic understanding of the core Ansible concepts to understand our documentation. Maybe it's worth adding a link to the official user's guide?

[acch]

I'm continuing my efforts to improve the documentation (#188). I've now added the following disclaimer:

Users need to have a basic understanding of the Ansible concepts for being able to follow these instructions. Refer to the Ansible User Guide if this is new to you.

Furthermore, I've adopted the README to be consistent with the wording used in the Ansible User Guide, and added links to the appropriate docs when using such terms.

If you have a minute to spare I'd appreciate if you could review my proposal and let me know what you think. Does this address the issue?