Merge "Adds the UX Personas descriptions."

doc/contributor-guide/source/index.rst

@@ -24,7 +24,7 @@ Contents
    doc-bugs.rst
    writing-docs.rst
    writing-style.rst
-   ui-text-guidelines.rst
+   user-guidelines.rst
    rst-conv.rst
    json-conv.rst
    diagram-guidelines.rst

doc/contributor-guide/source/user-guidelines.rst

@@ -0,0 +1,27 @@
+.. _user-guidelines:
+
+=======================================================
+OpenStack user experience and user interface guidelines
+=======================================================
+
+This section describes :abbr:`UX (User eXperience)`, :abbr:`UI (User
+Interface)`, and :abbr:`GUI (Graphic User Interface)` guidelines. It intends
+to improve OpenStack user experience by suggesting non-prescriptive methods
+and techniques in the following sections:
+
+#. UX Personas: The UX personas are intended as referential use-cases that
+   designers and developers can use when building content.
+#. GUI Guidelines: The GUI guidelines are intended for designers and
+   developers contributing content to GUI projects.
+#. UI Text Guidelines: The UI text guidelines are intended for designers,
+   developers, or reviewers contributing content within OpenStack user
+   interfaces.
+
+   .. toctree::
+      :maxdepth: 2
+
+      ux-ui-guidelines/ux-personas.rst
+      ux-ui-guidelines/ui-text-guidelines.rst
+
+.. TODO ux-ui-guidelines/gui-guidelines.rst
+

doc/contributor-guide/source/ux-ui-guidelines/ux-personas.rst

@@ -0,0 +1,143 @@
+.. _ux-personas:
+
+===========================
+Meet the OpenStack personas
+===========================
+
+In order to share the knowledge about the target users, we have created these
+representations of our key audience segments based on qualitative and
+quantitative user research. The goals are to create more empathy for our
+customers and to better display the different types of customers performing
+different jobs.
+
+We have identified five personas:
+
+* Arnie - Infrastructure Architect
+* Carlos - Cloud Operator
+* Doug - Domain Operator
+* Pei - Project Owner
+* Alan - App Developer
+
+These personas are based on model companies and user ecosystems. Each
+persona takes part in different cloud adoption stages and can assume multiple
+roles within each company.
+
+The personas
+~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   ux-personas/arnie-infrastructure-arch.rst
+   ux-personas/carlos-cloud-ops.rst
+   ux-personas/doug-domain-operator.rst
+   ux-personas/pei-project-owner.rst
+   ux-personas/alan-app-developer.rst
+
+
+The model companies
+~~~~~~~~~~~~~~~~~~~
+
+We have identified three organizational models that best exemplify the roles
+that the personas assume depending on their ecosystems.
+
+.. important::
+
+   The institutions described in this document are fictitious and serve only
+   as representations of different organizational models.
+
+Nikishi University - research
+-----------------------------
+
+At Nikishi university, each cloud user can potentially assume all personas'
+roles. Although typically each individual specializes in two or more of the
+roles. The Infrastructure Architect and the Cloud Operations roles
+could be assumed by a single individual. Similarly, the Domain Operations and
+Project Owner roles could be merged. This organizational model has a low
+staffing budget and is concerned with capital expenditure causing them to
+create their own implementation.
+
+.. list-table:: **Nikishi University - Key Info**
+   :widths: 15 15 15 15
+   :header-rows: 1
+
+   *  - Adoption model
+      - Process and compliance
+      - Skill depth
+      - Number of users
+   *  - Roll your own
+      - Minimal
+      - Deep
+      - 100 to 999 users
+
+CNBB Securities - large enterprise
+----------------------------------
+
+At CNBB Securities, the company's large organization chart represents each of
+the personas. Depending on the company's culture of collaboration, the
+personas could interact as if they were part of a single entity. However,
+usually the Cloud Operations and the Infrastructure Architect interact as
+service providers with the other personas. The personas within CNBB
+Securities look for a fast implementation and are responsible for the
+operations capital expenditure. The implementation has no customization and
+the organization usually outsources its support.
+
+.. list-table:: **CNBB Securities - Key Info**
+   :widths: 15 15 15 15
+   :header-rows: 1
+
+   *  - Adoption model
+      - Process and compliance
+      - Skill depth
+      - Number of users
+   *  - Distribution with professional services
+      - High
+      - Medium
+      - Over 10000 users
+
+Rifkom - service provider
+-------------------------
+
+At Rifkom, employees provide services to external customers that do not want
+or have the internal resources. Rifkom customizes solutions and
+prioritizes a flexible approach to architecture. The highly skilled staff
+represents the largest expenditure for Rifkom. Only Infrastructure Architects
+and Cloud Operators work at Rifkom since the other personas are their
+customers at MOI. Customers usually interact with Rifkom employees through a
+ticket system.
+
+.. list-table:: **Rifkom - Key Info**
+   :widths: 15 15 15 15
+   :header-rows: 1
+
+   *  - Adoption model
+      - Process and compliance
+      - Skill depth
+      - Number of users
+   *  - Roll your own
+      - Medium to High (depends on customer)
+      - Deep
+      - 1000 to 9999 users
+
+MOI - customer
+--------------
+
+At MOI, speed and convenience rule. Its staff encompasses the roles of App
+Developers, Project Owners, and Domain Operations. They do not perform any
+customization of the cloud and are willing to sacrifice functionality in
+order to save some costs. They interact with their cloud service provider,
+Rifkom, through a ticket system in case of problems with their cloud
+instance.
+
+.. list-table:: **MOI - Key Info**
+   :widths: 15 15 15 15
+   :header-rows: 1
+
+   *  - Adoption model
+      - Process and compliance
+      - Skill depth
+      - Number of users
+   *  - Professional services
+      - Medium
+      - Minimal
+      - No OpenStack users

doc/contributor-guide/source/ux-ui-guidelines/ux-personas/alan-app-developer.rst

@@ -0,0 +1,70 @@
+.. _alan-app-developer:
+
+============================
+Alan - application developer
+============================
+
+Alan develops and deploys applications for cloud instances running OpenStack.
+He does not know much about the underlying infrastructure of the cloud. The
+cloud instances he consumes can use various OpenStack projects. Alan does not
+know the names of the projects and has never been to an OpenStack summit.
+
+Alan wishes to deploy his applications to the cloud without issues and to
+receive warnings about any issues with the applications before tickets start
+coming. Whenever an issue arises during deployment or testing, Alan is
+grateful for clear uncomplicated notices. Such notices allow him to resolve
+the issues before customers become frustrated. Alan values a consistent API
+that makes his development future-proof and backwards-compatible.
+
+Key tasks
+~~~~~~~~~
+
+Alan performs the following tasks very frequently:
+
+* Development: Develops cloud-based applications with various requirements.
+
+* Management: Controls and changes all aspects of compute instances and file
+  storage.
+
+* Testing: Tests developed applications before deploying them. Performs the
+  tests in one or multiple cloud instances.
+
+* Deployment: Deploys his applications to one or multiple cloud instances.
+
+Key information
+~~~~~~~~~~~~~~~
+
+Alan spends very little to no time researching OpenStack. He does not care
+how the cloud instances he uses were installed, as long as they work exactly
+as he expects and the needed APIs do not change unexpectedly. He does not
+control what tool is used to install and maintain the cloud instances.
+However, he determines the requirements for those cloud instances.
+Any changes made to the APIs greatly impact Alan's work.
+
+The organizational models
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tasks that the persona performs within a certain organizational model are
+important for the usability of your OpenStack development. Within a small
+organization, such as Rifkom or Nikishi University, Alan might be required to
+assume some roles and responsibilities of a Domain Operator or a Cloud
+Operator. Within a larger organization, like CNBB Securities, Alan will
+likely not work alone on an application. Multiple application developers
+would need to access a single cloud to develop, test, and deploy the same
+application, making user control a requirement for the cloud.
+
+Your development
+~~~~~~~~~~~~~~~~
+
+Alan's main concern are the APIs available to him. Alan will not interact
+directly with OpenStack, save in rare cases or within small organizations.
+Therefore, changes to the GUI and CLI are not relevant to Alan. On the other
+hand, even the tiniest changes in APIs have a high impact on his application
+development.
+
+Alan assumes that the cloud has the resources his applications need. If the
+cloud does not have the resources, Alan expects the cloud to let him know
+what resources are missing in such a way, that he can ask a Cloud or Domain
+operator to add those resources. Alan will not add the resources himself.
+Therefore, ensure that notifications are clear and do not require any
+advanced knowledge of OpenStack to identify the issues.

doc/contributor-guide/source/ux-ui-guidelines/ux-personas/arnie-infrastructure-arch.rst

@@ -0,0 +1,64 @@
+.. _arnie-infrastructure-arch:
+
+================================
+Arnie - infrastructure architect
+================================
+
+Arnie is responsible for the strategy and road-map for his company's cloud.
+He identifies reasons to compel management to adopt OpenStack for production
+environments. The two reasons that would deter Arnie from recommending
+OpenStack are frequent instabilities, non-deterministic errors, the inability
+to create an environment, and missing documentation. Similarly to the domain
+operator, Arnie needs to know about any outage conditions that may occur on
+both testing and production environments.
+
+Key tasks
+~~~~~~~~~
+
+Arnie performs the following tasks very frequently:
+
+* Decision making: Considers adoption of OpenStack based on financial,
+  strategic, architecture, and security advantages.
+
+* Hardware configurations: Determines if a hardware configuration
+  suits the requirements of a cloud instance and if an OpenStack solution
+  running on such hardware is the best possible option.
+
+* User experience: Considers application developers, the development
+  processes, and the end users when recommending and installing cloud
+  instances.
+
+* Cloud planing: Defines and plans the cloud while considering hardware,
+  platform choices, services, and scale.
+
+Key information
+~~~~~~~~~~~~~~~
+
+Arnie spends a lot of time reading and researching information about
+OpenStack and other cloud technologies. He has attended more than one
+OpenStack summit and contributes solutions to the community regularly. He
+values OpenStack and is committed to drive adoption. His priority, however,
+is a fully functional and stable cloud that fulfills all of his requirements.
+
+The organizational models
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tasks that the persona performs within a certain organizational model are
+important for the usability of your OpenStack development. Within a small
+organization, such as Rifkom or Nikishi University, Arnie might be required
+to assume some roles and responsibilities of a Cloud Operator or, more
+rarely, a Domain Operator. Within a larger organization, like CNBB
+Securities, Arnie's tasks are performed by the team planing and implementing
+the cloud instances.
+
+Your development
+~~~~~~~~~~~~~~~~
+
+Arnie's main concern is the cloud's architecture. Arnie interacts directly
+with OpenStack and has probably developed any pieces that he needed. Your
+development targets Arnie if it makes any changes to the way clouds are
+implemented and deployed. Any new features, fixes, and limitations are
+important to him.
+
+If your development modifies the scope, implementation, and usage of
+OpenStack ensure to take Arnie into consideration.

doc/contributor-guide/source/ux-ui-guidelines/ux-personas/carlos-cloud-ops.rst

@@ -0,0 +1,68 @@
+.. _carlos-cloud-ops:
+
+=========================
+Carlos - cloud operations
+=========================
+
+Carlos is involved in installing, operating, using, and updating the
+OpenStack cloud services. Carlos ensures that the cloud is up and running. He
+must fix any issues as soon as possible. Collaborating with unskilled IT
+personnel is very challenging for Carlos.
+
+Key tasks
+~~~~~~~~~
+
+Carlos performs the following tasks very frequently:
+
+* Installation: Installs and configures OpenStack clouds often with the help
+  of the Infrastructure Architect.
+
+* Operation: Tracks day-to-day operation and administration of the cloud
+  including backup, disaster recovery, and platform services.
+
+* Usage tracking: Tracks the use that App Developers, Project Owners, and
+  Domain operators make of the cloud and optimizes the services accordingly.
+
+* Update: Performs updates and verification of the OpenStack cloud.
+
+Key information
+~~~~~~~~~~~~~~~
+
+Carlos spends some time every day searching for information on the OpenStack
+website. He has attended the OpenStack Summit once. He uses any tool he finds
+useful in operating the cloud. His previous role as a Linux system
+administrator influenced his decision to use OpenStack.
+
+The organizational models
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tasks that the persona performs within a certain organizational model are
+important for the usability of your OpenStack development. Within a small
+company, Carlos might be required to assume some of the responsibilities of
+both the Infrastructure Architect and the Domain Operator. Within a larger
+company, multiple individuals could perform subsets of Carlos's tasks. For
+example, one person could be in charge of installing and updating the cloud
+instances, while another could be in charge of monitoring operations and
+usage, and yet another person could be in charge of solving issues. In
+Carlos's organization, he is responsible for all of these tasks.
+
+Your development
+~~~~~~~~~~~~~~~~
+
+When your development affects the behavior of the cloud instances, you should
+consider Carlos as your target audience. Will your development change how the
+cloud is accessed, configured, monitored, or setup? Is your development
+changing the GUI, for example, the horizon dashboard? Carlos is unlikely to
+use :abbr:`CLI (Command-Line Interface)` to administer and track the cloud
+instances but is likely to use CLI to install and update them.
+
+Before submitting your code, think of the use cases that Carlos would follow.
+For example: Is it easy to use? Will Carlos get feedback when the task is
+complete? Are the changes in configuration reversible? How is the tracked
+information displayed? How long will the operation take?
+
+Finally, consider that Carlos is a highly skilled system administrator with a
+deep knowledge of OpenStack but with little time for long, complex research.
+Therefore, your solutions for Carlos must be quick to implement but do not
+need to shy away from complex OpenStack components, as long as they provide
+all the information needed within the solution itself.

doc/contributor-guide/source/ux-ui-guidelines/ux-personas/doug-domain-operator.rst

@@ -0,0 +1,70 @@
+.. _doug-domain-operator:
+
+======================
+Doug - domain operator
+======================
+
+Doug manages the relationship with the cloud services provider. This includes
+managing quotas, number of users, applicable policies, and support tickets.
+He does not have any major concerns about the underlying infrastructure of
+the cloud. He ensures that the :abbr:`SLA (Service-Level Agreement)` is
+followed.
+
+Doug needs to know about any outages, both scheduled and unscheduled.
+Unscheduled outages cause a lot of problems for Doug, as ideally there would
+never be an unscheduled outage.
+
+Key tasks
+~~~~~~~~~
+
+Doug performs the following tasks very frequently:
+
+* Managing quotas: Defines the amount of resources that the cloud service
+  provider must supply and ensures that those resources are being effectively
+  used.
+
+* Managing users: Defines the number of users with access to the cloud
+  services. He manages the access and rights of users for the entire cloud
+  services.
+
+* Ensuring SLA compliance: Monitors the various policies and support tickets
+  to ensure that the agreed terms are being fulfilled.
+
+Key information
+~~~~~~~~~~~~~~~
+
+Doug spends no time researching OpenStack. It is likely that he does not even
+know that the cloud service provider uses OpenStack. He does not care how the
+cloud instances are run, as long as they run without unexpected outages. He
+expects to be provided with adequate monitoring tools. Adding and removing
+users from the provided cloud services should be as easy as possible, in his
+opinion.
+
+The organizational models
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tasks that the persona performs within a certain organizational model are
+important for the usability of your OpenStack development. Within a small
+organization, such as Rifkom or Nikishi University, Doug might be required to
+assume some roles and responsibilities of a Cloud Operator or a Project
+Owner. Within a larger organization, like CNBB Securities, Doug's tasks are
+performed by the team managing the cloud services provider.
+
+Your development
+~~~~~~~~~~~~~~~~
+
+Doug's main concern are the cloud outages. Doug will not interact directly
+with OpenStack, save in rare cases or within small organizations. Therefore,
+changes that affect the stability and reliability of the cloud services are
+his greatest concern.
+
+Doug assumes that the cloud services provider will supply him adequate
+monitoring and user management tools. Doug expects the cloud to let him know
+the current status of the cloud in such a way, that he can ask the provider
+to solve it as quickly as possible. Doug will not fix the problems himself.
+Therefore, ensure that error notifications are clear and do not require any
+advanced knowledge of OpenStack to identify the issues.
+
+If your development modifies the user management of the cloud, ensure to take
+Doug into consideration. User management should be as simple as possible and
+it should not require deep knowledge about OpenStack.

doc/contributor-guide/source/ux-ui-guidelines/ux-personas/pei-project-owner.rst

@@ -0,0 +1,66 @@
+.. _pei-project-owner:
+
+===================
+Pei - project owner
+===================
+
+Pei manages projects by adding or removing project members' access to the
+cloud instance. Pei does not know the underlaying infrastructure nor the
+OpenStack projects involved. Pei's main concern is to have enough resources
+available to support her projects. Therefore, if a project runs out of quota,
+she does not want to have to wait for the operators to raise it.
+
+Key tasks
+~~~~~~~~~
+
+Pei performs the following tasks very frequently:
+
+* Managing access: adds and removes project members' access to OpenStack
+  resources.
+
+* Managing capacity: Requests additional resources through a
+  :abbr:`RUR (Resource Usage Request)`.
+
+* Managing projects: Coordinates project resources to ensure its success and
+  the OpenStack cloud is another resource among many other.
+
+Key information
+~~~~~~~~~~~~~~~
+
+Pei does not know or care about whether OpenStack is being used for the cloud
+instance her projects use or not. Her concern is to have the resources she
+needs when she needs them. If her requests for additional resources take too
+long to be fulfilled she will start looking for alternatives until the needs
+of her projects are met.
+
+The organizational models
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tasks that the persona performs within a certain organizational model are
+important for the usability of your OpenStack development. Within a small
+company, Pei might be required to assume some of the responsibilities of the
+the Domain Operator or maybe even the Cloud Operator. In this case, the
+persona does not need to submit requests to manage the cloud's resources but
+can rather make the changes needed.
+
+Within a larger organization, multiple individuals could be performing Pei's
+tasks. For example, each project could have a different person as a project
+owner and the company could have several projects.
+
+Whatever the case, it is highly likely that Pei is an experienced application
+developer as well. See the information pertaining to the application
+developer persona here: :ref:`alan-app-developer`
+
+Your development
+~~~~~~~~~~~~~~~~
+
+When your development affects the behavior of the capacity of cloud
+instances, you should consider Pei as an interested party. Ensuring that
+changes to the capacity of cloud instances can occur as easily and as quickly
+as possible certainly has a positive impact on Pei's work, for example.
+However, Pei does not perform those changes in capacity herself.
+
+Finally, consider that Pei is a highly skilled developer with little
+knowledge of OpenStack and with little time for long, complex research.
+Therefore, your solutions for Pei must be focused on enabling others to
+provide the needed resources as quickly as possible.