Re: [proposal] Consistency of naming in Cloudstack
+1 for instances As other public cloud (AWS, Azure, GCP) also use the term Instances or vm instances Regards Kiran From: Ayush Pandey Date: Monday, 12 June 2023 at 8:41 AM To: dev@cloudstack.apache.org Subject: Re: [proposal] Consistency of naming in Cloudstack Hi All, I've recently started working as a GSoC Contributor (Adding unmanaged instances for kvm hypervisor) and as a new cloudstack user I got really confused between the term instances and virtual Machine used interchangeably in UI/APIs, and it took me sometime to figure out both are the same thing. So +1 to Giles' proposal. Coming from the AWS ecosystem I think instances make more sense but I do understand from Daan's perspective why it is not a good choice. Best Regards, Ayush Pandey On Fri, Jun 9, 2023 at 12:34 PM Nicolas Vazquez < nicolas.vazq...@shapeblue.com> wrote: > +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 > Date: Friday, 9 June 2023 at 12:58 > To: 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 > Date: Thursday, 8 June 2023 at 16:46 > To: 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 t
Re: [proposal] Consistency of naming in Cloudstack
Hi All, I've recently started working as a GSoC Contributor (Adding unmanaged instances for kvm hypervisor) and as a new cloudstack user I got really confused between the term instances and virtual Machine used interchangeably in UI/APIs, and it took me sometime to figure out both are the same thing. So +1 to Giles' proposal. Coming from the AWS ecosystem I think instances make more sense but I do understand from Daan's perspective why it is not a good choice. Best Regards, Ayush Pandey On Fri, Jun 9, 2023 at 12:34 PM Nicolas Vazquez < nicolas.vazq...@shapeblue.com> wrote: > +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 > Date: Friday, 9 June 2023 at 12:58 > To: 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 > Date: Thursday, 8 June 2023 at 16:46 > To: 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 > > > > > >
Re: [proposal] Consistency of naming in Cloudstack
+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 Date: Friday, 9 June 2023 at 12:58 To: 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 Date: Thursday, 8 June 2023 at 16:46 To: 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
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 Date: Thursday, 8 June 2023 at 16:46 To: 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
Re: [proposal] Consistency of naming in Cloudstack
Giles, just about point one as the others follow from it. On Fri, Jun 9, 2023 at 10:17 AM Giles Sirett wrote: > > Hi Daan - thanks for your input. Some comments inline below > > > > Kind Regards > Giles > > > > > -Original Message- > From: Daan Hoogland > Sent: Thursday, June 8, 2023 4:17 PM > To: dev@cloudstack.apache.org > Subject: Re: [proposal] Consistency of naming in Cloudstack > > 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 > > >> I *think* I understand your point, but I see high correlation between > >> consistency of naming and clarity. Surely, using different names (or > >> metaphors!) for the same object type inherently reduces clarity?. Could > >> you give an example of where using different names for one cloudstack > >> object type could increase clarity ? When under "compute", there is the occurrence of "instance", this is not accurate. It is not a "compute instance". Would this item occur under "Virtual Machines" there would not be an issue. I am sure we can find many instances for the use of "instance" that would not refer to a VM instance. (that sentence was not more than a happy incident!) So far the only good argument I read about using "instance" is the fact that iot has already been used a lot. which is "kind of" weak. As far as I can see the industry is already doing damage control, specifying other uses of instance further to avoid cognitive clashes. > €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: wh
RE: [proposal] Consistency of naming in Cloudstack
Hi Daan - thanks for your input. Some comments inline below Kind Regards Giles -Original Message- From: Daan Hoogland Sent: Thursday, June 8, 2023 4:17 PM To: dev@cloudstack.apache.org Subject: Re: [proposal] Consistency of naming in Cloudstack 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 >> I *think* I understand your point, but I see high correlation between >> consistency of naming and clarity. Surely, using different names (or >> metaphors!) for the same object type inherently reduces clarity?. Could you >> give an example of where using different names for one cloudstack object >> type could increase clarity ? 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. >>To be clear here: this would involve renaming every UI element to >>standardise. Would you propose renaming the current main menu & lifecycle >>commands to one of these names ? 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. >> We'll have to agree to disagree on that €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
Re: [proposal] Consistency of naming in Cloudstack
+1 As long as we're not changing API names which would break backward compatibility, I think having clear, intuitive and consistent names and terminology in CloudStack UI and documentation for resources is a good idea and will be greatly improve and polish CloudStack. Historically, the word VM was never meant for compute instances like it is today. In computing, VM would refer to a virtual machine emulator which we can still see in the JVM, Erlang's Beam, etc also referred to as process virtual machines. What we think are VMs (thanks to VMware's product and marketing) popular much later on were system domains or system virtual machines that can emulate a whole computer system. Some hypervisors historically and still today (KVM, Xen/XCP-ng...) refer to them as domains. When these remote machines, jails or sometimes domains started running in headless remote environments (data centers), they were referred to as virtual personal server (VPS) or just virtual servers and eventually cloud or compute instances. I think the word compute instance or instance are quite popular, clear and intuitive word when used in an IaaS/cloud platform (in all opensource, closed cloud platforms and on public providers). In the UI, historically and in recent times, we've always referred to VMs as "instances". In the legacy and current UI, the VM tab was/is called "Instances" under the Compute group, and most of the VM actions forms also refer on instances such as - edit/start/stop/reboot/reinstall/migrate instance. However, in documentation we sometimes refer instance to a VM and otherwise instance in other places. I wouldn't want to change the reference in the UI, so ideally some labels in the UI and docs should be fixed instead. Despite our passionate thoughts, we can't honestly expect industry to follow us or adopt terminologies that we define. As an active participant we should use terms that are in the best of CloudStack project and the user community. I think all user-facing things should be clear and consistent, without consistency as a new user I may be confused when say referring the CloudStack documentation and the UI. Most users I think start with both UI (and docs). Regards. From: Daan Hoogland Sent: Thursday, June 8, 2023 20:46 To: dev@cloudstack.apache.org Subject: Re: [proposal] Consistency of naming in Cloudstack 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 d
Re: [proposal] Consistency of naming in Cloudstack
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
[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
