A Self Help project contains a set of business processes described in procedures in order to enable users to access a knowledge base that can help them troubleshoot, find solutions and make decisions.

It is deployed in several phases:

• Design and preparation
• Self Help project initialization
• Definition of design and writing best practices and standards
• Initialization of Self Help project content, followed by writing and translation
• Publication of the Self Help project and continual improvement of content

Design and preparation

Goal and objectives of the new Self Help project

Identifying the objectives, needs and expectations of end users as regards the new Self Help project helps you design and structure the project, determine its main characteristics, define content, and identify the physical and human resources required for deployment, etc.

Examples

• Deploy a Self Help project to reduce the number of calls to the Service Desk.

• Enable users to access the knowledge base for one of the company's applications.

Notes

• The implementation of a virtual agent is performed using a specific project methodology.
      See Deploying a virtual agent.

Functional scope of the Self Help project

The functional scope encompasses the scope of action of the new Self Help project. It defines the business processes to be created and the content to be written.

The scope must be clearly defined in order to create a knowledge base that meets the needs of end users.

It must be considered:

• In terms of its interface with third-party products, in order to install connection packages required for communication between these products, e.g. Service Manager, Salesforce, virtual agent, etc.

• In terms of architecture, for the installation of the customer portal, i.e. single-project or multi-project portal, based on the diversity of its target audiences.

• In terms of the project's display channels, in order to adapt procedures accordingly, e.g. portal, virtual agent, Web application, etc.

• In terms of content, in order to determine the number of writers required and identify the business processes to be written.

• In terms of translation for multilingual projects, in order to plan the human resources and time required for translation, adapt the procedures to cultural and legal constraints by contextualizing information.

Examples

• Deploy a Self Help project to reduce the number of calls to the Service Desk ==> Define priority procedures based on the ten most common incident categories, or the ten most commonly asked HR questions, etc.

• Deploy a portal by adapting the design and content of procedures to different target audiences ==> Create a multi-project portal by isolating content in different Self Help projects.

•  Enable users to access the knowledge base for one of the company's applications ==> Install a ready-to-use knowledge base package with the most commonly asked questions.

• Deploy a multilingual HR project ==> Adapt the content of certain procedures to the legislation applicable in each country.

Best Practice

• Create an initial version of your Self Help project from the analysis of the functional scope so that you can make the knowledge base available quickly to end users.
• Subsequently, you can broaden the scope of action of your Self Help project in the continual improvement phase by publishing major versions.

  example  Version 1: Integrate the existing formatted procedures; Version 2: Add connectors

Integration of existing components

Instead of starting your Self Help project from scratch, you can reuse existing components.

• You can initialize the structure by duplicating an existing  Self Help project.

• You can create a customer portal quickly using a standard project template, e.g. a Self Help project with no content but with the structure and layout already defined for an optimal display of the portal using the evSH skin.

• You can import content from an existing knowledge base from Word documents or question/answer Excel files. Procedures will be automatically created from each Word document page and each Excel file row.

• You can use standard generic procedures.

• You can download procedure packages and adapt the procedures to the new Self Help project.
           See List of available templates.

Self Help project initialization

Appointment of administrators

The new Self Help project must be implemented in a domain that is hosted on a server. Domains enable you to define access restrictions for writers and users. You must appoint the administrators in charge of these two components from the start of the Self Help project, prior to structuring the workspace.

Server administrators

Server administrators are appointed when the Self Help application is installed. They are in charge of the server and have an overview of the domains associated with it. Their role is as follows:

• Create domain administrators and manage their access rights.
• Create and manage domains and storage space.
• Manage the licenses associated with their server.
• Manage the connection flows of connectors.
   

Domain administrators

They are appointed by the server administrator and are in charge of one or more domains. Their role is as follows:

• Manage access rights for writers, users and groups within their domains.
• Configure the connectors used by the Self Help projects in their domains.
• Provide skins applicable to the Self Help projects in their domains.
• Implement virtual agents for the Self Help projects in their domains.

They are also owners of all Self Help projects in their domains. As such, they have all rights to create, modify, delete and publish.

Notes

• A server administrator account is valid only for a given server. 
• Server administrators are not writers or users. They can only access the Desktop Studio in admin mode and are restricted to server administration functionalities in the Online Studio.
• For SaaS-based customers:
  • There are no server administrators. These duties are performed by the EasyVista team.
  • The domain administrator account is used to manage all domains.

• A domain administrator account is used to manage several domains as long as they are hosted on the same server and the server administrator has assigned the relevant rights for each domain.
• Server administrators can create as many domains as they want.
• A Self Help project is created for a single domain. You can export and install it in other domains. Caution: This requires regular maintenance of the Self Help project in each of the domains.

Best Practice

For server administrators

• Create two different domains:
  • Sandbox, for the test environment
  • Production, for importing the final tested versions of your Self Help projects

• You should appoint two or more administrators for each domain so that there is always a backup.

Self Help project structure

A Self Help project is made up of a set of procedures and can use a group of resources such as documents, forms, connectors, variables, scripts, etc. You must organize and structure the Self Help project right from the start to make it easier for writers to access its content. You should create folders and subfolders, group resources based on type, etc.

The structure of the Self Help project must also take into account:

• Specific aspects relating to the Self Help project's display channel, e.g. customer portal, Web application, virtual agent, etc.

• The translation aspect for a multilingual project so that the Self Help project can be organized based on the need for contextual adaptation, e.g. one subfolder for each language, etc.

• The multi-project aspect when the knowledge base contains different content whose publication frequency differs significantly, when it has different confidentiality levels, or when it contains procedures accessed by diverse target audiences, etc.

Example of a Self Help project tree structure

Notes

• The customer portal is based on the evSH skin. The tree structure of the Self Help project enables you to provide browsing through three levels of Web pages automatically. The names of the three levels are identical to the names of folders and subfolders.

• The connection packages imported to perform integrations of third-party products within a Self Help project will appear in the domain as individual Self Help projects with their own structure and organization.
   

     Automatic creation of special folders:

• In the tree structure of the Self Help project:
  • Library: Library containing the macros (scripts) and variables used by Self Help projects.
  • Recycle bin in edit mode: Space where the procedures, folders, or resources deleted within the Self Help project are stored.

• In the tree structure of the domain:
  • Recycle bin in publish mode: Space where Self Help project versions deleted within the domain are stored.

Best Practice

• Use one of the import functionalities to automatically structure the Self Help project.
  • You can perform a mass import of Word documents contained in a folder. The Self Help project will be identical to the tree structure of folders and subfolders in the file explorer.
  • You can import a question/answer Excel file. The Self Help project will be based on the folders specified in the Excel file.

• If you create a virtual agent, isolate the procedures specific to it in another Self Help project.

• Give a meaningful name to folders and subfolders so you can easily identify their contents.
• Avoid creating too many specific categories in the tree structure of your Self Help project as both writers and users will be confused when browsing or running searches.

• Create Resources subfolders near the procedures that use them.
• Manage the shared resources of your procedures at the root of the Self Help project.
• Create subfolders for each type of resource, e.g. icons, images, PDF files, etc.
          

User and writer authorizations

Different collaborators play different roles throughout the entire Self Help project. The diagram below shows these roles:
        

Writers

Writers are usually knowledge experts. They write and publish procedures.

• They are authorized to work on the Self Help project based on their read, write and publish rights.
           See Access rights management.

• They are supervised by the knowledge manager.
  • Much like a project manager, the knowledge manager monitors and organizes the work of writers.
  • The knowledge manager also ensures that the topics covered by the virtual agent fall within the functional scope of the Self Help project.

• Note: The domain administrator is a specific writer who can access the Desktop Studio in admin mode to manage the access rights of writers, users and groups belonging to the domain.
   

Users

Users can access knowledge content in the Self Help project based on the rights assigned to the groups where they belong.

• User groups contain lists of users associated with a given domain.  They can be created using various criteria, e.g. department, location, level of skill, etc.
• Only published project procedures that can be run by users are accessible.

Notes

• Depending on the importance of the project, there may be a project manager. If this is the case, the project manager will be in charge of decisions relating to the entire Self Help project and will coordinate the team of writers while the knowledge manager will be in charge of written content within the Self Help project.

• Users and user groups must be created to enable the first publication of the Self Help project. As a general rule, they are not identified from the start of the project. However, you can start referencing certain information during the initialization phase.

• The server administrator has access to the Online Studio to perform the mass import of users. 

Best Practice

• Create authorization matrices for users and writers in tabular format to start identifying writer access rights, groups, Self Help project sections and procedures which users will be able to access, ...

Definition of best practices and standards

Defining the best practices and standards prior to the start of the writing phase ensures the quality and consistency of the Self Help project as regards the organization of its resources and content.

• By defining the naming convention and the guidelines for organizing folders, procedures and resources, you can structure the Self Help project and facilitate its use for all writers.
• Guidelines for structuring procedures enable users to focus on content instead of layout.
• Writing guidelines ensure the consistency and standardization of procedures, even though they may be written by different writers.
   

All of these best practices and standards must be grouped in a style guide specific to the Self Help project.

Non-comprehensive list of contents in a style guide

The objective of the style guide is to standardize elements in the Self Help project as much as possible in order to facilitate the work of writers.

It must be defined by each customer based on corporate practices. It should, however, contain the following:

• Guidelines for organizing the Self Help project, e.g. structure, hierarchy of information, elements arranged in folders or subfolders.
• Guidelines for organizing resources based on type and use by other Self Help projects within the domain, etc.
• Guidelines for naming folders, resources, procedures, steps and variables, etc.
• Guidelines for structuring elements.
• Guidelines for specifying metadata in procedures.
• Guidelines for formatting visible steps for users.
• Guidelines related to text style and formatting.
• General best writing practices.

Examples

• Start the name of the resource with the initial of its type, e.g. F for forms, C for content, etc. The name is then followed by a few letters associated with the procedure to which it is related.

• Choose step names that are short and meaningful. Specify the step number in the procedure so users know where they are.

• Use action verbs in procedures to engage users.

• Highlight examples, notes and comments using different colors, bold or underlined text, etc.

Best Practice

• Incorporate existing guidelines and standards from other Self Help projects and from your corporate style convention in the writing style guide.

• Explain the importance of complying with all of the guidelines for the Self Help project to different collaborators.

• To facilitate compliance with the style guide when writing procedures, implement the content validation workflow for all Self Help project procedures.

• Enhance and update your style guide because it should be continuously improved.
  • Add or adapt the guidelines throughout the Self Help project based on the needs identified by the knowledge manager.
  • Distribute the style guide to all writers.

Initialization of Self Help project content

During the design and preparation phase, you defined the functional scope of the Self Help project and took into account the integration of existing components. Before starting the writing phase, these considerations will help initialize the knowledge base for the new Self Help project.

• Which ready-to-use templates can be installed to create a portal or deploy a virtual agent?
• Which connection packages should be installed for interfacing third-party products with the Self Help project?
• Is there any existing knowledge content in Word documents or in question/answer Excel files that can be easily retrieved and imported in order to create procedures quickly and automatically?
• Can the resources and procedures available in other Self Help projects be reused?
   

Writers can access a toolkit to help them structure and define the layout of procedures in a consistent way. It is easily accessible in the tree structure of the Self Help project and can contain the following:

• Generic procedures
• Procedure templates with the most commonly used types of steps
• Examples of steps and procedures, such as standard step-by-step procedures, procedures with choices, etc.
          

Notes

• The toolkit must be isolated in a hidden folder to ensure its contents are invisible to users.
• The resources shared by procedures are managed outside the toolkit so they can be run by users.

• The Self Help project can integrate resources and procedures from other projects in different ways:
  • Using a procedure alias, to call a procedure from another Self Help project within the same domain. In this case, the content of the procedure is not copied to the Self Help project. Instead, a dynamic link with the source project is created. 
  • Using the copy/paste function if the resource or procedure is associated with another Self Help project within the same domain. You can use the export/import function if it is associated with a Self Help project from another domain. In this case, the object contents are copied and pasted in the Self Help project.

Caution

• Each time the Self Help project is published, you must ensure that users cannot run any of the procedures in the toolkit.

Best Practice

• Prioritize the use of procedure aliases to call procedures from other Self Help projects. In this way, any modification made to the source project will automatically be propagated to your Self Help project. When you use the copy/paste function or export/import function, you must perform maintenance to keep procedures up-to-date in each relevant project.

• To access the toolkit quickly, add [999] to the start of the folder name. This ensures that it is always displayed at the bottom of the Self Help project tree structure when sorted by alphabetical order. Note: You can add the text, 999 within square brackets [ ] to ensure that it will not appear in the folder name.

  example  [999] Templates ==> The folder name displayed at the bottom of the tree structure is Templates.

Knowledge base content

Role of writers

• The first task for writers is to collect all of the knowledge content required for writing procedures. Collaborating with business users is also a good approach to organizing procedures.
• Next, writers will define the structure of procedures by creating steps and the required resources.
  • You can use the copy/paste function if the resource is associated with another Self Help project within the same domain, or use the export/import function if the projects are not within the same domain.
• Writers will write the knowledge content in compliance with the style guide. Writers can:
  • Leverage the templates and examples of procedures in the toolkit, by duplicating them first in the target folder to avoid overwriting them.
  • Call procedures from other Self Help projects within the same domain using their procedure alias.
  • Use the copy/paste function if the procedure is associated with another Self Help project within the same domain, or use the export/import function if the projects are not within the same domain.
• Once all of the procedures in the Self Help project have been validated, writers must update non-translatable metadata, i.e. metadata not affected by language.
   

Role of the knowledge manager

• As project manager, the knowledge manager must monitor and organize the work of writers throughout the writing phase.
• The knowledge manager must also ensure that procedures comply with the style guide to ensure the consistency of content in the Self Help project. This can be done using the content validation workflow.

Notes

• You can update metadata individually in the Properties view in edit mode, or you can update metadata in a batch by exporting and importing a CSV file.
• Translatable metadata, i.e. metadata affected by the language, must be updated once the writing phase is completed, which is generally before the translation phase.

Best Practice

For writers

• Divide procedures up into steps based on the average user's knowledge. If required, add certain branches for new users and other branches for experts.
• Create sub-procedures to isolate procedures that are common to several procedures. This makes long complex processes (usually with more than five steps) easier to read.
• Add satisfaction surveys at the end of procedures to allow users to send feedback and give a score. This feedback can be used to define areas of improvement during the continual improvement phase.
   

For the knowledge manager

• To accelerate content validation, you can assign content validation rights to experts. You must first ensure that validation rules have been defined.

Translation of a multilingual Self Help project

All components in a multilingual Self Help project can be translated, e.g. folder names, procedure names, text in steps, form fields, etc. Translatable metadata, i.e. metadata affected by language, can also be translated.

This should be done once all procedures have been validated and just before the Self Help project is published. Writers can perform the translation in different ways.

Translation methods

You can use a combination of methods to translate Self Help project components.  See Management of multilingual Self Help projects.

• Translate each component individually in edit mode in the Desktop Studio:
  • Translation is performed for each language.
  • This means that you have to access each component and translate them individually, i.e. elements in the tree structure, procedure step names, text in steps, resource content, etc.

• Perform the translation by exporting and importing a translation archive for the Self Help project:
  • A translation archive is created for a given language and for selected components.
  • Translation is done directly in the exported XLIFF files.
  • Once translation is done, you reimport the archive to the Self Help project.

• Use the automatic translation tool for procedure steps and HTML content resources:
  • Translation is performed for each language in the Conception pane in edit mode.
  • The text in the source language will automatically be translated into the target language.
  • If required, you can make modifications manually to the translation for each of the languages.

Translation of translatable metadata

Translatable metadata must be translated into different languages. To do this, you export the metadata in CSV files and then reimport them to the Self Help project once translation is done.

The metadata will automatically be propagated to all procedures in the Self Help project when it is imported.

Notes

• To select the translation languages, access the Desktop Studio in edit mode and select Help > Preferences > Allowed Languages in the menu.

• To create a translation archive, access the Desktop Studio in edit mode and select Translation > Export text files for localization in the menu.

• Exporting/Importing metadata:
  • To export metadata, access the Desktop Studio in edit mode and select Export > Get Metadata in the menu.
  • To import metadata, access the Online Studio and select Import > > Attributes in the menu and click Import attributes.

• XLIFF files (Localization Interchange File Format) require industry-specific software for performing the translation.

Best Practice

• XLIFF files contain numerous tags in XML format. We therefore recommend that you ask a translation agency to perform the translation using industry-specific software. Industry-specific software use translation memories that store and reuse segments of sentences subsequently. This means that only translatable data you have added or modified from one version to the next will be processed.

• Combine the different translation methods to meet your needs. For example, you can perform an automatic translation of procedures and then make manual corrections to the translation for each individual component.

• If you perform the translation using a translation archive, you should lock the Self Help project as long as the translation archive has not been reimported. If any modification is made to the content in the meantime, the exported file will no longer be valid.

Publication

Publication of the Self Help project gives you a snapshot of the project at a given time that can be used for testing, acceptance or deployment. You do this in edit mode. This will create a project version.

You can then inform the end users authorized to access the new version of the Self Help project.

Prerequisites to publishing a version

• Once the content validation workflow has been implemented, the status of all content in the Self Help project must be Approved.
  • Note: You can force this status for all content that has not yet been validated when publishing.

• Procedures accessible to users must be authorized to run directly.
  • You can configure this for each procedure in the Properties view in edit mode.
  • Note: You can also configure this during publication when the entire tree structure of procedures is displayed.

• In a multilingual Self Help project, you must translate components and translatable metadata for all languages.

• You must create the users and user groups authorized to access the version.
  • Each published version is associated with user groups. Only users in these groups can access the version in read mode.
  • Each time you publish a new version, you can add or delete user groups.

Creating users and user groups

Creating user groups

*User groups contain lists of users associated with a given domain.

• They can be created using various criteria, e.g. department, location, level of skill, etc.

• The server administrator or domain administrator can create them by accessing the Desktop Studio in admin mode.

• By default:
  • A group created by the server administrator cannot access any domain.
  • A group created by the domain administrator can only access that domain.
  • Groups cannot access any Self Help project when they are created.

Creating users

• You can create them in two ways:
  • By delegating user authentication to a third-party identity provider using just one set of credentials (SSO for Single Sign On):
    • When users log in for the first time, they create their account with the mandatory information, i.e. login, first name, last name, email address.Note: Depending on the exchange protocol, other information in user properties can be retrieved from the third-party identity provider.
    • Users who are created in this way will automatically belong to the same publication groups as authenticatedUser and will have the same rights. Note: The authenticatedUser account is present by default in each domain.
       
  • By performing a mass import of users using a CSV file:
    • To import users, the server administrator should access the Online Studio, select Import > Users in the menu and click Import Users.
    • User rights are subsequently assigned in admin mode in the Desktop Studio.

• By default:
  • Users are not associated with any domain or any group when they are created.
  • Users cannot access any Self Help project.

Notes

• Publication can be performed:
  • By domain administrators
  • By the owner of the Self Help project
  • By writers with publish rights (read, write, approve and publish rights).  See Access rights management for Self Help projects.

• Version numbering for published versions is automatic and is used to identify their type.
  • Major version: Planned version
  • Minor version: Correction of errors and bugs

• You can define public access for the Self Help project. This means that any user can access the Self Help project in read mode.
  • Public access is applicable to all versions of Self Help projects within the domain.
  • To do this, you must create a Public account. You must tick the Connection without password box for this public user. You must then associate it with the Self Help project.

• Writers can run all procedures in the Desktop Studio. However, when writers access the portal, they access it as users based on their user groups.

You manage published Self Help projects in the Desktop Studio in publish mode. Version management enables you to archive versions or rollback to a previous version if required.

Best Practice

• For multilingual Self Help projects, make sure that the names and text seen by users are translated into each of the languages before publishing.
• Run the publication of projects in scheduled tasks during off-peak periods to avoid slowing down the server.
• If there is a blocking problem with the new version, you can generate a new minor version to provide a quick fix for the Self Help project while adopting more in-depth corrective actions.

• Define a regular communication strategy for your Self Help project by informing users of its deployment, updates, major changes in design or scope, etc.

Continual improvement

The objective of the continual improvement phase is to improve the solution implemented. The continual improvement process is used to improve quality and performance once the Self Help project is deployed. To do this, you can define a review and publication calendar to evaluate the situation at regular intervals with the different collaborators of the Self Help project.

The approach is specific to each customer based on their objectives and their scope of improvement. Customers can use different tools to help analyze their Self Help project, e.g. reports, KPIs, user feedback, etc.

You manage the different continual improvement phases through the new major versions of the Self Help project and their distribution to end users.  See Version management of Self Help projects.

Examples of improvements

• Improve the search function using keywords in procedures.
• Add new functionalities requested by users.
• Provide tips on using the portal.
• Correct errors reported by users and check that they do not occur again.
• Improve the readability of the style guide.

Performance analysis tools

You can use different tools in Self Help to analyze the project.

• The Online Studio provides statistical reports that perform a detailed analysis of Self Help project procedures, such as usage frequency, user journeys, search details, answers returned by the virtual agent, etc.

• The analysis of user feedback helps identify the issues encountered, user satisfaction as regards procedures via the scores awarded, and requests for change.

Notes

• You generate statistical reports in the Online Studio by selecting the Analytics menu.
  • Statistical reports can be accessed by administrators and writers depending on their Self Help project rights.
  • Results are displayed in statistical reports in Excel format.

Best Practice

• Ask new writers to take part in reviewing your Self Help project in order to bring a fresh perspective and objective feedback as regards procedures.
• Define an order of priority for the implementation of improvements by including, for example, an assessment of the costs of correction and the time spent by the Support team on processing user questions.