Welcome to the documentation pages of the your (sub)product name of openCX!
You can find here detailed about the (sub)product, hereby mentioned as module, from a high-level vision to low-level implementation decisions, a kind of Software Development Report (see template), organized by discipline (as of RUP):
- Business modeling
- Requirements
- Architecture and Design
- Implementation
- Test
- Configuration and change management
- Project management
So far, contributions are exclusively made by the initial team, but we hope to open them to the community, in all areas and topics: requirements, technologies, development, experimentation, testing, etc.
Please contact us!
Thank you!
team members names
Start by defining a clear and concise vision for your module, to help members of the team, contributors, and users into focusing their often disparate views into a concise, visual, and short textual form. It provides a "high concept" of the product for marketers, developers, and managers.
A product vision describes the essential of the product and sets the direction to where a product is headed, and what the product will deliver in the future.
We favor a catchy and concise statement, ideally one sentence.
To learn more about how to write a good product vision, please see also:
- How To Create A Convincing Product Vision To Guide Your Team, by uxstudioteam.com
- Product Management: Product Vision, by ProductPlan
- Vision, by scrumbook.org
- How to write a vision, by dummies.com
- 20 Inspiring Vision Statement Examples (2019 Updated), by lifehack.org
Draft a small text to help you quickly introduce and describe your product in a short time and a few words (~800 characters), a technique usually known as elevator pitch.
Take a look at the following links to learn some techniques:
- Crafting an Elevator Pitch
- The Best Elevator Pitch Examples, Templates, and Tactics - A Guide to Writing an Unforgettable Elevator Speech, by strategypeak.com
- Top 7 Killer Elevator Pitch Examples, by toggl.com
In this section, you should describe all kinds of requirements for your module: functional and non-functional requirements.
Start by contextualizing your module, describing the main concepts, terms, roles, scope and boundaries of the application domain addressed by the project.
Create a use-case diagram in UML with all high-level use cases possibly addressed by your module.
Give each use case a concise, results-oriented name. Use cases should reflect the tasks the user needs to be able to accomplish using the system. Include an action verb and a noun.
Briefly describe each use case mentioning the following:
-
Actor. Name only the actor that will be initiating this use case, i.e. a person or other entity external to the software system being specified who interacts with the system and performs use cases to accomplish tasks.
-
Description. Provide a brief description of the reason for and outcome of this use case, or a high-level description of the sequence of actions and the outcome of executing the use case.
-
Preconditions and Postconditions. Include any activities that must take place, or any conditions that must be true, before the use case can be started (preconditions). Describe also the state of the system at the conclusion of the use case execution (postconditions).
-
Normal Flow. Provide a detailed description of the user actions and system responses that will take place during execution of the use case under normal, expected conditions. This dialog sequence will ultimately lead to accomplishing the goal stated in the use case name and description. This is best done as a numbered list of actions performed by the actor, alternating with responses provided by the system.
-
Alternative Flows and Exceptions. Document other, legitimate usage scenarios that can take place within this use case, stating any differences in the sequence of steps that take place. In addition, describe any anticipated error conditions that could occur during execution of the use case, and define how the system is to respond to those conditions.
This section will contain the requirements of the product described as user stories, organized in a global user story map with user roles or themes.
For each theme, or role, you may add a small description. User stories should be detailed in the tool you decided to use for project management (e.g. trello or github projects).
A user story is a description of desired functionality told from the perspective of the user or customer. A starting template for the description of a user story is
As a < user role >, I want < goal > so that < reason >.
INVEST in good user stories. You may add more details after, but the shorter and complete, the better. In order to decide if the user story is good, please follow the INVEST guidelines.
User interface mockups. After the user story text, you should add a draft of the corresponding user interfaces, a simple mockup or draft, if applicable.
Acceptance tests. For each user story you should write also the acceptance tests (textually in Gherkin), i.e., a description of scenarios (situations) that will help to confirm that the system satisfies the requirements addressed by the user story.
Value and effort. At the end, it is good to add a rough indication of the value of the user story to the customers (e.g. MoSCoW method) and the team should add an estimation of the effort to implement it, for example, using t-shirt sizes (XS, S, M, L, XL).
To better understand the context of the software system, it is very useful to have a simple UML class diagram with all the key concepts (names, attributes) and relationships involved of the problem domain addressed by your module.
The architecture of a software system encompasses the set of key decisions about its overall organization.
A well written architecture document is brief but reduces the amount of time it takes new programmers to a project to understand the code to feel able to make modifications and enhancements.
To document the architecture requires describing the decomposition of the system in their parts (high-level components) and the key behaviors and collaborations between them.
In this section you should start by briefly describing the overall components of the project and their interrelations. You should also describe how you solved typical problems you may have encountered, pointing to well-known architectural and design patterns, if applicable.
The purpose of this subsection is to document the high-level logical structure of the code, using a UML diagram with logical packages, without the worry of allocating to components, processes or machines.
It can be beneficial to present the system both in a horizontal or vertical decomposition:
- horizontal decomposition may define layers and implementation concepts, such as the user interface, business logic and concepts;
- vertical decomposition can define a hierarchy of subsystems that cover all layers of implementation.
The goal of this subsection is to document the high-level physical structure of the software system (machines, connections, software components installed, and their dependencies) using UML deployment diagrams or component diagrams (separate or integrated), showing the physical structure of the system.
It should describe also the technologies considered and justify the selections made. Examples of technologies relevant for openCX are, for example, frameworks for mobile applications (Flutter vs ReactNative vs ...), languages to program with microbit, and communication with things (beacons, sensors, etc.).
To help on validating all the architectural, design and technological decisions made, we usually implement a vertical prototype, a thin vertical slice of the system.
In this subsection please describe in more detail which, and how, user(s) story(ies) were implemented.
Regular product increments are a good practice of product management.
While not necessary, sometimes it might be useful to explain a few aspects of the code that have the greatest potential to confuse software engineers about how it works. Since the code should speak by itself, try to keep this section as short and simple as possible.
Use cross-links to the code repository and only embed real fragments of code when strictly needed, since they tend to become outdated very soon.
There are several ways of documenting testing activities, and quality assurance in general, being the most common: a strategy, a plan, test case specifications, and test checklists.
In this section it is only expected to include the following:
- test plan describing the list of features to be tested and the testing methods and tools;
- test case specifications to verify the functionalities, using unit tests and acceptance tests.
A good practice is to simplify this, avoiding repetitions, and automating the testing actions as much as possible.
Configuration and change management are key activities to control change to, and maintain the integrity of, a project’s artifacts (code, models, documents).
For the purpose of ESOF, we will use a very simple approach, just to manage feature requests, bug fixes, and improvements, using GitHub issues and following the GitHub flow.
Software project management is an art and science of planning and leading software projects, in which software projects are planned, implemented, monitored and controlled.
In the context of ESOF, we expect that each team adopts a project management tool capable of registering tasks, assign tasks to people, add estimations to tasks, monitor tasks progress, and therefore being able to track their projects.
Example of tools to do this are:
We recommend to use the simplest tool that can possibly work for the team.
Describe your contribution to open-cx (iteration 5), linking to the appropriate pull requests, issues, documentation.