Update style guide with preferred terminology

[samccann]

To ensure we are consistent in naming projects and what not, we should define our common terms and add them to the docs style guide.

This is a scratchpad where we can decide the terms and then someone can create the PR as an good first issue.

https://hackmd.io/SH4UvQCHS4OcRsRY5qLi0A

[gotmax23]

Quick brain dump. I'll elaborate here later or in the next DAWGs meeting.

Ansible lint

Ansible Lint or ansible-lint

Ansible Molecule

Molecule or molecule

execution environment

Sure.

Ansible Playbooks
Ansible Roles
Ansible Rule
Ansible Rulebook

I don't think we need title case here.

[samccann]

Updated the hackmd accordingly, thanks! The one thing I put there is the firs time someone talks about something (e.x. molecule) it should be Ansible Molecule. After that, we can drop the Ansible part except for Ansible Lint imo.

[gotmax23]

• automation content navigator Ansible Navigator on first occurance. Subsequent occurances can be navigator or ansible-navigator if referring to the CLI.

I'd say we should always call it Ansible Navigator or ansible-navigator. The project/package name is Ansible Navigator.

On the other hand, I don't think we need to say Ansible Molecule (just Molecule or molecule). The project/project name doesn't have Ansible in it.

[gotmax23]

I'd also figure out how we want to name/differentiate ansible-core and the ansible package. Sometimes people use upper case Ansible which can be ambiguous.

[Landrash]

Looks really good.

For readability it should probably be Ansible navigator and shorthand Navigator since that then substitutes the name of the tool.

[Fale]

I think "execution environment" should follow the same rule of playbooks:

• Ansible execution environment on first occurance. Subsequent occurances can be execution environment.

Also, not native speaker, but is "occurance" correct? Shouldn't it be "occurrence"? (this comment is valid for the whole document)

[Fale]

Also:

• Ansible rulebook on first occurance. Subsequent occurances can be rule.

Should be

• Ansible rulebook on first occurance. Subsequent occurances can be rulebook.

[samccann]

thanks all. I've updated the hackmd.

[leogallego]

@samccann we might want to add the following to the list and keep them consistent with Ansible Navigator:

• ansible-builder
• ansible-runner
• ansible-rulebook (in the list, but not consistent)
• ansible-sdk
• ansible-sign
• ansible-test (this one might be like ansible-core though? as in only named as the CLI command?)

Also, we might want to keep the Caps for subsequent mentions to avoid confusion between referring to the command/tool vs a normal word in a blog post for ex. (Navigator, Builder, Runner, etc.)

[samccann]

Thanks @leogallego - The caps aren't necessary in that regard because the cli commands should always be formated as ansible-foo so to speak so can't have any confusion between the name of a project or feature and the matching CLI.

[Fale]

I don't think we should encourage EE to refer to execution environments, if we opt for uncapitalized form, since it would be weird to do so

[felixfontein]

According to http://docs.testing.ansible.com/ansible/devel/dev_guide/style_guide/spelling_word_choice.html#acronyms it should be EE for execution environment(s).

[Fale]

An acronym is an acronym if a group of people decides to use it in that way. My point is not to suggest a different acronym (eg: ee), but to avoid suggesting an acronym at all, in the same way that we do not use AP for Ansible playbooks, etc

[oraNod]

+1 for avoiding suggesting EE. It's a good opportunity to come to a consensus on this one as it is gaining acceptance.

I feel like the whole purpose of EE is to have a shorthand for the writer because using "execution environment" repeatedly is kind of a chore. As a reader, though, I think EE as a standalone acronym is slightly confusing.

My preference for the guidance here would be something like use "execution environment" in reference to the abstract notion and then a format like "<image-name> EE" for specific examples and when referencing known container images. Prefixing EE with the image name makes it a bit more concrete and might help avoid readers needing to do any mental gymnastics.

[Fale]

Also "EE", for many tech people, is associated to Java (J2EE) and stands for Enterprise Edition.

[oraNod]

ansible-core - always refer to ansible-core. Should never be Ansible core.

Why never Ansible core?

[samccann]

Why never Ansible core?

This was my attempt to clear up the confusion with all things named Ansible. I figured if in the docs, we never say Ansible core, but always ansible-core then that's at least one place where the term Ansible only refers to the package. That said, it's probably not clearing anything up really so I could remove it and say Ansible core except when referring to the install, where it is ansible-core.

[leogallego]

Thanks @leogallego - The caps aren't necessary in that regard because the cli commands should always be formated as ansible-foo so to speak so can't have any confusion between the name of a project or feature and the matching CLI.

Hey @samccann to give some context, I'm talking about capitalization as a means of distinguishing what are looking more and more like actions / common words from the actual tools / applications, not for the CLI command itself, but when talking about it.

For ex. talking about Execution Environments, or Builder, or any other tool without capitalizing makes it harder to distinguish the use depending on the context. Several of the projects are being named after common words (Lint, Navigator, Builder, Sign, Runner, Receptor... etc.), capitalization helps to quickly figure if we are talking about the tool or not, even if we are not referring to the CLI to run a command.

This also helps international users, as some might have a hard time some times using translation tools to figure if something is an action or a tool when checking documentation. We have run into translated project names several times (even within Ansible projects user interfaces), using Caps is a clear sign that's not a simple word.

In my opinion we should stick to capitals if we are not using the CLI command, I see it as an accessibility issue.

@oraNod:

I feel like the whole purpose of EE is to have a shorthand for the writer because using "execution environment" repeatedly is kind of a chore. As a reader, though, I think EE as a standalone acronym is slightly confusing.

@oraNod And the above about keeping Caps would make using EE valid again after a full first "Execution Environment (EE)" in the text. I agree it might be slightly confusing on first sight if there is no full name before, but people tend to use acronyms for a reason and it's the same we use automation: we are lazy :D

[Andersson007]

My suggestion would be:

1. Use the full technology name on first occurrence, e.g.: Ansible Core, Ansible Lint, Ansible Execution Environments. If there are abbreviations used along the text, they follow the technology name on first occurrence being in brackets, e.g. Ansible Execution Environment (EE).
2. Subsequent occurrences if there's no associated CLI tool, can omit Ansible but must start with a capital latter, i.e. Core, Execution Environments (as technology).
3. If there's a command-line tool associated with the technology, it must be used on subsequent occurrences and be highlighted, e.g. ansible-navigator.
   4 When referring to a particular entity, i.e. a sample of something, lowercase should be used: a playbook, an execution environment, a rule, etc or an abbreviation if applicable and was specified as mentioned in p.1.

Examples:

• Ansible Execution Environment (EE) on first occurrence. Subsequent are:
  • when referring to technology: "Execution Environment" or "EE"
  • when referring to a sample of technology: "an/the execution environment" or "an/the EE"
• Ansible Lint on first occurrence. All subsequent are ansible-lint
• Ansible Core on first. All subsequent are Core.
• Ansible Navitagor on first. All subsequent are ansible-navigator
• Ansible collections on first All subsequent are collections.
• Ansible Builder on first. All subsequent are ansible-builder.
• etc.

Speaking about Ansible as a special case. If the word order the Ansible community package is correct from the grammar perspective, I would slightly prefer this one (though the suggested is also fine).

I think i'm generally agree with what @leogallego is saying above.
Tough question:)

[oraNod]

Why never Ansible core?

This was my attempt to clear up the confusion with all things named Ansible. I figured if in the docs, we never say Ansible core, but always ansible-core then that's at least one place where the term Ansible only refers to the package. That said, it's probably not clearing anything up really so I could remove it and say Ansible core except when referring to the install, where it is ansible-core.

By the same token I feel like if you want Ansible to only refer to the package then you should only use ansible. Maybe rather than having a guideline of "never say Ansible core" we could add some more nuance and encourage phrasing like "Ansible core runtime and language" to be really explicit about what core means. In fairness that would probably be in conceptual docs and might be less common for community writers. For command line stuff and programmer docs then ansible-core def makes sense. I just think absolute rules are restrictive and can lead to esoteric patterns.

[oraNod]

I also generally agree with @leogallego and @Andersson007 but still don't think "EE" should ever be standalone in a sentence. It's not a hill I want to die on though.

What would be great here is a visualization of all these things with the naming conventions. Sort of like the Fedora org chart but for the Ansible ecosystem.

[tvo318]

@oraNod - in the rst, we used a variable (|ee| = execution environment) to make it convenient for writers to not have to spell it all out. Could we do the same int his context?

[oraNod]

@tvo318 I suppose we could do that but I'm not sure if that adds to complexity for contributors. If we did, I'd prefer to put any of those variables somewhere other than the conf.py file too.

[Andersson007]

not to bikeshed, maybe we should submit a PR reflecting the suggested options based on thumbs up or whatever? We could skip EE for now.
The experience is saying that when there's a PR, things are moving.

[samccann]

Good idea. I'll open a PR with the contents of the hackmd and see how it goes :-)