- Created by Robert Reiner, last modified on 24. Nov 2020
projectdoc Toolbox
Defines a role with its responsibilities, tasks and requirements. Roles are incorporated by stakeholders who take interest in the project. The are also used to define the audience for documents.
- ID
role- Suite
- Documentation Type
- Categories
- Tags
A role document instance defines the role of a person, system, or organisation that an actor in a use case may hold.
Definition
Our use of the term role is based on the following definition:
role, n. any part played by something (e.g. a person, piece of equipment, or organization)
Donald G. Firesmith, Sally Shlaer and Stephen Mellor
A role captures the purpose of something, the position it holds, or its capacity, job, or viewpoint.
Donald G. Firesmith
An actor in the Unified Modeling Language (UML) "specifies a role played by a user or any other system that interacts with the subject." Anonymous. Wikipedia
Information provided by Roles
Use this document type to describe the role's
- responsibilities
- tools it works with
- requirements it imposes on the product
- consequences for the project
For more information on this, please refer to Uwe Friedrichsen Wer hat Angst vor dem Betrieb?.
The document will automatically
- list all uses cases the role plays a part in.
- list all quality scenarios the role is mentioned as a stimulus.
- list all user characters that hold this role.
- list all stakeholders that hold this role for this project.
This automated linking helps to find relevant information for a given role in your wiki easily.
Properties
The document type role provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Besides the standard document properties, this doctype provides no specifics properties.
Sections
The document type provides the following sections.
Description
A general description of the role.
Responsibilities
The responsibilities of the role describe what stakeholders, holding this role, have to do or care for. This allows to identify which tasks a role has to perform.
Tools
Describe the tools a role uses or requires to perform its tasks. This allows to identify interfaces the system under development has to provide to communicate with the role's current tool set.
Requirements
List the requirements the role imposes on the system under development. List functional and non-functional requirements.
Implications
Describe the implications the role has on the design of the system under development. This may be in the form of a bullet list, references to individually subdocuments with more detailed information or to complete design documents.
We would suggest to use design documents and place them as children to the role document. If the design is relevant to more than one role, move it to the design document section. But there is nothing wrong to start with a small bullet list, but keep in mind that those collections may be less easy to find.
Specialized Roles
Lists automatically the subdocuments of this document type.
It is assumed that every subrole is more specific than its parent roles. That is, it uses the same tool set and has the same, but maybe more specific responsibilities.
It is usually advantageous to have a limited number of roles. Try to find the essential roles of your project. Organize them hierarchically to keep the number of base roles (those without a role parent) small. This reduces complexity.
If you can think of subroles you have no user stories or use cases for, you might want to mention them in their own section on the parent role's document first.
If you have a set of roles that may take part in a use case, but not all of its siblings, you may be about to discover a yet unnamed role that is relevant to your project.
Use Cases
Lists automatically the use cases where actors holding this role act as
- primary,
- secondary, and
- supporting.
Primary Actors
This role is referenced as a primary actor in the use cases listed here.
Secondary Actors
This role is referenced as a secondary actor in the use cases listed here.
Supporting Actors
This role is referenced as a supporting actor in the use cases listed here.
Quality Scenarios
Lists automatically the quality scenarios that refer to this role.
User Characters
Lists automatically the user characters that hold this role.
Stakeholders
Lists automatically the stakeholders that hold this role.
Reports
List report types the members of this role are interested in.
See Stakeholder where this information is used to create a communication plan.
Since 16.0
This property is available since version 16.0.
Communicates
List report types the members of this role produce to communicate to other stakeholders.
See Stakeholder where this information is used to create a communication plan.
Since 16.0
This property is available since version 16.0.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Details
Different Kind of Roles
There is only this one document type that captures all kinds of roles that are relevant to the system.
Therefore we do not distinguish between project roles that take part to create a product and roles users of the product have. There may also be support roles, like first-level support, operators, system administrators that may or may not require to be considered for the project.
Related Doctypes
Stakeholder and Person
A stakeholder is a person with interest in a project or the result of a project. A stakeholder therefore maps a person to a role within a given project. A person may take part in many projects, but is only represented as a single stakeholder per project. A stakeholder may have many roles in a project.
User Character
A user character is an actor within a user story. Typically, if you document a user story, you have a particular role in mind. Therefore user characters and roles often map 1:1. But the actor within a user story may also be a persona (e.g. Personas example @ Atlassian) or an extreme character. Both are creative tools to enhance the quality of your user stories and tighten the understanding of your problem domain.
Therefore there is a need to separate the roles from user stories by the notion of a user character. If you do not want to use personas, extreme characters or user characters that have several roles, you might want to skip user characters and edit your user story template to refer to roles instead of user characters.
Use Case
A use case document references roles as actors that take part in a given use case. With this you can easily identify the use cases a particular role takes part.Quality Scenario
A quality scenario documents may reference roles as stimulus on an artifact in a given environment.Resources
- Stakeholder
- A party that takes interest in a project. The stakeholder is either a real person, an organization or group, or represents a class of individuals, groups or organizations.
- Report Type
- Group your reports by a self-defined type.
