ALM User's Guide

Working with text design artifacts in Devprom ALM is no different from using conventional word processors. A powerful WYSIWYG editor toolbar is displayed above the editing area, with which you can format text, insert tables, images, mathematical formulas, UML models, diagrams, etc.

Some project artifacts, such as requirements or test documentation, are presented in the form of documents, i.e. sections that are related to each other. Each section represents a header, general information, an atomic requirement, or a test case. Sections can be nested within each other, thereby forming a hierarchy of requirements, sections of test documentation, etc.

New sections are created using:

• context menu in the Contents;
• Links: Insert requirement and Create child;
• green button with the + symbol

The Insert requirement link allows you to add a new section below the current one and at the same hierarchy level. The Create child link is used to create a nested section (subsection) relative to the current one.

You can select the document display mode:

• only one section
• or several sections at once

In the document view settings, you can also select additional information that should be displayed in the document tree (contents), for example, UID, section status, etc.

To save these settings for this view, use the standard feature - the Save link, which will appear in the filter settings field.

Reviewing a document

While working with documents, questions and comments regarding the text may arise. By selecting part of the text, you can add a comment. An additional pane on the right displays pending comments on the document. By clicking on a comment you can go to the corresponding section of the document.

Using the Comments filter, you can display only those sections of the document that have pending comments, or only your comments. This significantly speeds up the document approval process.

Signal that a comment has been taken into account (implemented by making changes), or is no longer relevant (if a comprehensive response has been provided), by using the status of the comment: closed or open. Managing the comment status is available using a checkmark in the comments pane on the right, or using the context menu on the Comments tab on the document section editing form.

When working on projects, you may have external documents received, for example, from the customer or other sources. To save and use these documents in your project you can:

• import them, the application supports import from PDF, MSWord, OpenDocument, HTML, Excel;
• attach to sections of the knowledge base or requirements as files.

Any file can be attached to a document section using the Files link, or through the artifact card: Additional tab, Applications field.

When importing documents, the application will split it into parts according to the markup with heading styles. Each part of the document will become either a separate section of the knowledge base or a separate requirement.

Documents can be imported into specific sections using the item Create - Child - Import:

You can import a previously exported document. In document mode, in the "Actions" menu there is a corresponding "Import" item.

The system identifies document sections by title. But, since a document may have duplicate headings, this mechanism is best used with documents whose headings contain identifiers of artifacts (requirements, test documentation, etc.). In this case, the system clearly understands in which section of the document the imported block of text needs to be loaded.

The width of the columns in the table can be fixed using sliders. Creation/deletion of columns or rows is carried out using the context menu.

Images can be pasted from the clipboard using keyboard shortcuts or the context menu. You can insert images located on your PC using the button on the editor toolbar. Resize the image if necessary by dragging the lower right corner.

For the purpose of version control and auditing of changes, images are stored entirely within document sections, so sections can take up a significant amount of space. The larger the volume of the section, the more difficult it is for the browser to work with such a section, and the delay when loading and saving such a section increases.

We recommend inserting several large images into a section of the document, and saving the remaining images in separate sections.

When preparing project documentation, for example, business or system requirements, it is good to use various expressive tools: UML models, BPMN diagrams, graphical interface layouts, decision trees (mental maps, mind maps), etc.

The editor has built-in support for UML models, implemented using PlantUML. This is a simple language that allows you to describe UML models of various types in text form. The source code (text) of the model is stored directly in the document section, so each participant in the process can make changes to the current version of the diagram.

When you click the Diagram button on the toolbar, the popular draw.io editor will open, in which you can create diagrams in completely different notations. It's a great alternative to Visio and similar desktop tools. The source code (text) of the diagram is stored directly inside the requirement, so versioning, version comparison, and other mechanisms for managing requirements and changes used for the text work.

If necessary, you can create diagrams using the desktop version of draw.io and then import them into your document.

If you use other tools to prepare diagrams, you can insert the result of your work as an image or embedded HTML. Moreover, if the source model or diagram is updated, they will be updated in the requirement text. This is achieved by inserting the model as embedded HTML (Embedded HTML). Almost all tools allow you to insert models as inline HTML.

On the toolbar, select the Insert HTML button and paste into the input field the text that the modeling tool showed you.

Here is a list of several popular modeling tools:

• https://cawemo.com/for building BPMN diagrams
• https://www.gliffy.comfor drawing diagrams
• https://moqups.comfor drawing GUI

This method has a number of limitations. For example, such diagrams cannot be uploaded to external formats if authentication is required, or they are stored on a private cloud drive.

Use diagrams to create decision trees (mental maps). Add a new diagram and in the "Advanced" section, select the ready-made Mind maps shape.

You can create branches, topics and ideas using the arrows on the diagram:

To create GUI mockups, insert a diagram and select shapes (Mockup...), where you can find all the basic controls for mocking up a GUI user interface. If there is no such category of shapes, then click the More shapes button and connect the necessary categories.

You can place links to other project artifacts in the text to quickly jump to them, or to analyze and track dependencies. Using the button on the editor toolbar or using the Insert link to artifact context menu you can open the artifact search window.

If the title of a section or artifact changes, the title of the link will also change.

To add a link with the name (text) you need, use the standard buttons on the editor toolbar.

You can specify a link to the project artifact as the link address.

If you insert a link to another requirement into the text of a requirement, the latter will have a back link in the Used field in the Traces section. This field is available for display in modules and reports. This way you can track requirements that reference this. The same applies to other types of documentation: test and operational.

You can insert an arbitrary module (system or user) into the editor text to display data in tabular form on the page. This table is updated dynamically and can be exported to an external format. Examples of using an embedded table:

• Release notes
• List of works/tasks marked with the tag
• Risk management plan
• List of related requirements
• Requirements tracing, etc.

To insert a module, you need to click the corresponding button on the toolbar and select the desired one from the drop-down list. To customize the table view (remove unnecessary or add missing columns), you can go to the module, make the necessary settings and save the changes. It is better to create your own based on the module for the purpose of using it on the page. Then, its settings will not be accidentally changed when used to solve other problems.

Here is use of Terms module in the "Definitions, Acronyms, and Abbreviations" section of SRS document:

Contents

A special Contents of the requirements document module allows you to insert the contents (or table of contents) of the document into the page:

In the text of artifacts, pages, and sections of documents, you can display attributes of the artifact itself, or data from artifacts associated with it. This is achieved by inserting attributes into the editor text.

When specifying a formula to calculate the value of an attribute, use [D-5781] Query language syntax. The formula must be contained in curly braces, for example

Add pre-prepared texts in a couple of clicks. Use the Text Templates setting to create pre-made texts that you can then paste into the editor by entering the hash (or sharp) symbol (#). This way, you can organize template substitution for user stories, requirements or standard answers in comments.

You can insert the text of design artifacts within the text of other artifacts, for example, to ensure that some reusable text appears across many pages in one or more documents. If the source text changes, it will automatically update in the section where it was inserted. To insert text, use the corresponding button on the editor toolbar, or the Insert text action in the editor context menu:

The artifact text selection form has a Spoiler field, which allows you to hide the text inside the click-drop-down control (spoiler).

You can reuse an entire section of a document, or an entire branch of a document within another document. For this purpose, the Include in document operation is provided, or you can add an artifact to the document structure by using an existing:

You can create a complete copy of a document or a hierarchy of artifacts, such as requirements or test documentation. Thus, it is convenient to replicate the standard documentation structure.

To create standard documents with a pre-filled structure and content of some sections, use the Save as template action:

Manage your project directly from the knowledge base, requirements or test documentation - create tasks or requirements and track their status directly in the text of the article. References to completed tasks or requirements are crossed out.

In the same way, it is convenient to decompose imported requirements into child (atomic) requirements. Just select the required text and select the Create requirement action:

To include media content (videos) in the description of a task, requirement or knowledge base article, use the corresponding button on the editor pane.

The documents you prepare can be uploaded to external formats such as MSWord, OpenDocument, PDF, HTML. When uploading to MSWord, you can use a sample (template) of the document into which you want to upload the text. In the sample document, styles can be declared, headers and footers, title pages, etc. can be added.

Technically, free external tools are used to upload documents to PDF, MSWord or OpenDocument format: Imagick, PanDoc or LibreOffice (OpenOffice). The availability of upload operations is determined by the presence of these components on the server where Devprom ALM is installed. Check if LibreOffice is installed on the server. If for some reason this application cannot be used, then install PanDoc on the server.

Upload options

Re-import a document

A document previously unloaded from the system can be re-imported to reflect changes made to the file by process participants who do not have access to the system.

The operation is available in the Actions button in the document mode.

Selective export

You can upload not only a document. You can upload a single section or any set of sections selected in the list. When working in document mode, you can also use filters that allow you to select only the necessary sections of the document for uploading.

For example, if you don't need some sections in the resulting document, mark them with a tag. In the filter settings, select only those sections that do not have tags and upload the document. The upload will not contain the sections that you tagged.

Use a query language to select those document sections that should be uploaded to an external format.

Export document attributes in a template

When exporting a document using a template, you can export attributes of the document itself, for example, Title, Author, as well as attributes of any section of the document. To do this, you need to insert a Field with a special name in the template text, for example:

0

so that the document's name is inserted into the document field when uploading. You can use any document attributes, as well as calculated attributes.