Giles, the principle of what you are saying seems good but I have a few remarks;
1. Consistency should not become a goal. Clarity is and if context
might give rise to a different understanding of the same work
consistency is detrimental to understanding
2. Metaphor is an important aspect in system development [1] first
introduced into software development in xtreme programming [2] I think
instance is a bad metaphor to use for Virtual Machine Instances in a
system that is full of all kinds of items (first class citizens) that
can also be seen as instances. I would go for "VM instance",
"VM-instance" or just machines. I am not saying either of these are
ideal but they are all better than instance.
and finally
3. The industry standard is not a good reason to go for a term. we can
improve on the industry standard and so we should.
€0.02
[1]
https://medium.com/swlh/the-importance-of-metaphors-in-programming-philosophy-and-trading-a0030ed176b6
[2] http://www.extremeprogramming.org/rules/metaphor.html
On Thu, Jun 8, 2023 at 4:47 PM Giles Sirett wrote:
>
> 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
>
>
>
>
--
Daan
