+1 thanks Giles.
For the API we could also update the API docs descriptions for methods,
parameters, and response fields (even though we can end up with: parameter:
virtualmachineid and description: ‘Instance ID’ for example)
Regards,
Nicolas Vazquez
From: Marco Sinhoreli <marco.sinhor...@shapeblue.com>
Date: Friday, 9 June 2023 at 12:58
To: dev@cloudstack.apache.org <dev@cloudstack.apache.org>
Subject: Re: [proposal] Consistency of naming in Cloudstack
+1 to use “Instance” in the UI and docs. Everyone knows what " Instance " is,
in my view, just a label to refer to an object in ACS. As Rohit said, it is
under Compute, then it refers to a Compute Instance.
From: Giles Sirett <giles.sir...@shapeblue.com>
Date: Thursday, 8 June 2023 at 16:46
To: dev@cloudstack.apache.org <dev@cloudstack.apache.org>
Subject: [proposal] Consistency of naming in Cloudstack
Background
Recently, I have been looking at a number of issues relating to the "first
use" / "first impression" use of cloudstack. What to people think of
Cloudstack as a new user? What is peoples perception of Cloudstack as a new
user ? How easy is it for people to understand cloudstack & its concepts and to
get help
One thing I have seen is that CloudStack is inconsistent with what we call
VM's/Instances:
* In the UI main menu, we say Instances. We then have a very large "Create
instance" button. All lifecycle operations are then "Foo Instance"
* In various other places in the UI (many text messages, error messages,
column headers, for example) we say "VM"
* The API uses Instance, VM and Virtual Machine
* The documentation, again, uses all 3 terms
Now - I know everybody on this list (myself included for the last 10 years) has
always used these terms interchangeably - we all KNOW that these are the same
things. However, I think it could cause confusion to people seeing Cloudstack
for the first time and create negative impressions. Also, there is no
consistency when searching documentation - one page uses one term, one the
other (and some even use both on the same page) . I don't know of many other
pieces of software that use 2/3 different names for their primary functional
object
My proposal is to move towards having consistency of this naming and would
look something like this:
1. Choose the name to use going forwards (more on that later)
2. Undertake a remedial exercise:
* Update UI elements to [new name]
* Update documentation to [New Name]
* Leave Global Settings names alone, but change their description to
reflect [New Name]
* Leave the API alone - theres no way of getting consistency there
without breaking compatibility
3. Encourage contributors to use [new name] in all work going forwards
The remedial exercise (hopefully) could be a find/replace (with some manual
checking) - I'd be happy to take that on with some help from work colleagues
As/when/if we do do Cloudstack 5.0, then look at the API, but IMO this is
lower priority as people that's not usdually "first impression"
So - first proposal point: any objections to me undertaking this work ?
Second point: what to call these things ?
It is my view that we should call them Instances. These are my reasons:
* Nearly all Cloud computing platforms refer to them as instances (i.e.
industry standard) . Yes, it is a VM "behind the scenes", but Instance is an
accepted term that is slightly abstracted from VM
* Our primary UI already uses Instance ns most prominent places, renaming
top level nav and functionality is a step backwards IMO
* Today, Cloudstack provides these through VMs , but that could change in
the future (please don't read anything into that comment) - instance doesn't
tie us to VMs (which is probably why most cloud providers use it)
So, my proposal is to bring consistency and use the term Instance
>From brief discussions, I know other people favour other terms and may have
>objections to the term Instance (despite it having been in use in ACS for many
>years) - but happy to take all inputs if people feel this is just wrong.
Kind Regards
Giles
