General

Structure & Usage of the Documentation

The documentation of Vote follows a clear thread to make even the most complex functions understandable to everyone. In order to be able to follow and understand the thread, for example to know which subsections are irrelevant and which are important for the overall understanding, this section serves. The documentation has several subsections:

• General General guidance on how to classify the information and use the documentation. Vote itself is not complex, but many of the components are non-trivial, so jumping directly to the content points might cause problems if the context is not known.

• Users The creation of votes creates user profiles for the creators. Which possibilities of the configuration the users possess is explained here more exactly

• Vote Object Introduction of the Vote Object with all components, settings, configuration options, functions etc.

• Clients These areas build on the Vote object and presuppose this knowledge. They contain information, how Vote can be used concretely in the individual components and which characteristics there are with the versch. Clients exist.

• API The documentation of the API is outsourced to OpenAPI Doku and is there also only available in English.

• Change History In the last part of the documentation you can find the change history. There you can find all changes in the different versions. The highlights can also be found on the start page of the guide.

Important If simple introductory videos are needed to get a first understanding, it is best to have a look at Demos.

All components of the documentation and the demos can be searched using the search function. However, the API is excluded from this, as it stands for itself. The documentation serves as the basis for all components of Vote and is therefore linked at various points when using the guides to provide a seamless transition between using Vote and reading various information.

Usage of Vote

Full use is currently still reserved for Deutsche Telekom employees and all subsidiaries, including, for example, the creation of new votes. However, in order to enable employees and external parties (customers, developers, etc.) to participate in votes, Vote is otherwise accessible and usable for everyone. The identification of internal employees is based on the IP address, which is briefly compared with the released IP addresses in case of requests. Therefore, employees on company laptops are not recognized as such, unless they are using a VPN, etc. To enable our employees to use certain internal functions on other devices as well - possibly non-managed laptops - there is the option of using the access key/API key to obtain access from outside the Telekom network. A so-called access key can be generated on the dashboard page of the individual user after he has created at least 1 vote. Otherwise, the use of Vote and all components is subject to the Terms of Use.

Terms

In order to be able to introduce Vote functions and components more specifically in the following, the basic terms of Vote are introduced afterwards:

• Vote: This is both the system and a created main object within the system, such as a survey, Q&A, ...

• QuestionBlock: Basic elements of a vote are the question blocks, which cluster the questions/objects within a vote according to semantic affiliation. They form a logical bracket and can provide the user with additional information (title, description,...) to better answer the underlying questions.

• Question: The atomic element of a Vote is a question, which can be represented differently depending on the module. Therefore, a question can be, among others, a MultipleChoice, FreeText, WordCloud, Q&A and behave differently in various situations depending on the setting of the respective question. However, the actual use of a question depends on the settings of the parent Vote.

• Module: A module is a logical grouping of functions and settings in Vote. Vote currently has two modules: Vote (survey) and Interactive Tools (interactive), each of which is used for different use cases and must adhere to different regulations

• User: Vote does not have an account system. However, in order to offer users the possibility of having an overview of all their votes, user-objects are created for each user. Through an anonymous ID, which can only be requested via an email, a user can then receive an overview of his votes in the form of a dashboard.

• AnonymousUser: An anonymous user is created for each participant, which is used to participate in a vote and to store the user's settings (alias & team). As long as the user does not enter any user-related information into the alias, it is impossible to assign participants to the AnonymUser.

• Answer & React: The actual answer to a question is represented by an answer. A reaction to it, e.g. comment or thumbs up, is represented by a React in the system.

• Session: This is a context in the system that represents either the current context of a user or the assumed context of an invitation. By using a client & server side authentication/authorization, the context of a user/invitation can still be changed afterwards on the server side, if for example an invitation was sent incorrectly.

• Invite: Invitation to vote for a specific participant in the form of a mail (default) or one of the integrations.

System functionality and components

In addition to the functionalities of individual votes (participation, analysis, etc.), Vote also has system functionalities that are necessary for the overall operation. In the following, these system functionalities will be described in more detail:

• Languages: Interfaces (web/integrations) in German and English, depending on settings in Vote or Browser/Client.

• Themes: Surface designs (web) depending on user preference (Dark/Bright Theme).

• Pro/Easy Mode: (Web only) Users can set how much information/functionality they want to see from Vote to avoid being overwhelmed if necessary.

• Reserver ID: (Only api currently) Reservation of Vote IDs, e.g. to offer certain codes for certain events. (Non-numeric codes must be requested from system administrators beforehand).

• Template Validation: (Only api currently) Validation of Vote Templates with subsequent feedback for revision.

• OpenAPI Documentation: Detailed documentation of Vote's REST API with the ability to perform operations directly.

• Dashboards: Overview of all votes of a specific person, without automatic authorization of votes.

• IFrame: (Not yet available) Support for IFrames to embed Vote on other pages.

• MOTD: Message of the day - possibility to get current information about the system to the users.

• Reminder: Reminders for users when e.g. Vote will be deleted in the near future.

• Translate: (Only api currently) Since Vote objects can be offered in different languages, the Telekom translation tool is used for automatic translation, if requested by the user.

• Run: (Only api currently) Run of a Vote, to which the respective answers are assigned in the time period.

Modules

As described in one of the last sections, modules represent logical groupings of settings and functions in Vote. Due to the different use cases of the individual groups, different rules can be applied and a stricter distinction can be made between the areas. For example, anonymity must be provided for polls and surveys, but strict anonymity would be counterproductive for a Q&A in the interactive domain, which means that optional personal binding must be allowed.

• Survey: Anonymous survey of users on a specific topic with later evaluation. (e.g. KBV Evaluation, Befragung).

• Interactive Tools: (Only api currently) Tools to support agile work, e.g. Q&A, Planning Poker, Meeting Finder ... (a.o. KBV digital collaboration).