Documents

Documents

Documents is a computer aided systems engineering tool with the capabilities of managing the content of many types of engineering documents. It does this by presenting a tabular editor that turns ordinary document drafting into a database.

Document types

V-Raptor documents are extensible through document types. New types can be created to categorise the different types of documents created within your organisation.

Create a document type

1. Click on the menu button to open the menu

   

2. Make sure the organisation you are creating the prefix for is selected

3. Click the gear icon next to the organisation name to go to the settings screen for your organisation

   

4. Click the Document types menu option

5. Click the New document type button

6. Fill in the new document type form

   Name: give the new document type a name

   Description give the new document type a description

   Prefix select a prefix for numbering new documents

   Template select an existing document to be forked and act as a template for new documents

7. Click Create

Document structure

Documents have several parts

• Branches
• Revisions
• Properties
• Enumerations
• Attachments
• Entities
• Sheets
• Columns
• Clauses
• Fields
• Links
• Views

Branches

Each new document will be created with a default branch. The name of the default branch is copied from the organisation settings. By default the default branch is named main.

Branch management will be enabled in a future release

Revisions

Document revisions are the commit objects that represent the structure of the document at the time of the commit.

Custom properties

Custom properties allow additional meta data to be included in exported documents. These properties are attached to DOCX documents as custom properties. Custom properties can be referenced within an attached DOCX template to customise DOCX exports using fields.

Enumerations

Enumerations are custom data types that consist of a list of text values that can be selected from a menu.

Attachments

Attachments are images that are attached to fields with the image data type.

Entities

Entities are things that can be physical or abstract that are referenced within a document, and which have a definition. Entity definitions can be exported as a definitions section in a DOCX export.

Sheets

Each document must have one or more sheets which allow long documents to be managed in sections. Each section has it's own set of columns.

Each sheet has a default body column that represents the main body of text of the document.

Columns

The data structure of a sheet is defined by the columns in the sheet. Each sheet has two calculated columns, a default column, and can have any number of custom columns.

Id column

The id column assigns a unique auto-incrementing number to each clause within the document. The ids are assigned to each clause when they are committed (saved) to V-Raptor.

Number column

The number column assigns a number to each clause. The clause numbering follows an indentation rule that prepends the number of the parent clause to the clause number seperated by a period .. Clause numbering can be customised with the following sequences.

• None
• Bulleted
• Number (1, 2, 3, ...)
• Lower case alphabet (a, b, c, ...)
• Upper case alphabet (A, B, C, ...)
• Lower case roman (i, ii, iii, ...)
• Upper case roman (I, II, III, ...)
• Lower case greek (α, β, γ, ...)
• Upper case greek (Α, Β, Γ, ...)
• Lower case cyrillic (а, б, в, ...)
• Upper case cyrillic (А, Б, В, ...)
• Chinese (CJK) (一, 二, 三, ...)

Body column

The body column is a special custom column that cannot be removed. The body column contains the main body of text of the document.

Custom columns

Custom columns can be added to each sheet in a document. Each custom column on a sheet must have a unique name. Custom columns can be assigned a default data type for all the fields in the column.

Custom columns can be used to annotate the body column for example adding a rationale or justification.

Clauses

Clauses are the rows of text in a document. For example in a requirements document, each clause should represent a single requirement.

Clause numbering

Clauses are assigned sequential numbers when they are committed to the document. A single pool of numbers is assigned to the document across all branches to prevent conflicts when merging.

The clause number prefix is assigned to the clause copied from the document clause prefix. Any parameters in the document clause prefix are flattened.

Fields

Fields are the cells in which data for each clause, column position is input.

Each field can overwrite the data type and view styling for its column.

Field data types

Fields have a data type that allow different types of data to be inserted into a document.

Type	Description
Text
Check box	Boolean data that is either true (ticked) or false (unticked)
Number	IEEE double precision floating point data. Number data can also be formatted for display in different notations. Decimal Scientific Engineering
User	A select box that allows selection of a member from the organisation.
System	A select box that allows selection of a system or subsystem from the organisation.
Image	An image attached to the document.
Enumeration	A select box that allows selection of an enumerated value.

Links

Links provide traceability between document clauses. V-Raptor has both incoming and outgoing links. Outgoing links are saved with the revision history of the current document, whereas incoming links are saved with the revision history of the document at the link origin.

Views

Each document has a default view that controls layout of each sheet.

Sheets can be made visible or hidden and invidiual columns can be made visible or hidden within a sheet. The visibility of sheets and columns is reflected when documents are exported.

The sheet properties panel and column properties panel include a number of options for styling the sheet when being exported. These styles are applied to the current view.

Document collaborating

Multiple members of an organisation may work on a document branch at the same time. When another user opens the document, their icon or initials will be shown within a coloured circle in the top right of the toolbar.

When another user has a field selected, the field will be outlined with the same colour that the user's icon is outlined with. Users can avoid edit conflicts by only editing fields another user isn't working on.

When another user stages a change to the document, the changes will be updated for all other users editing the same branch of the document.

When collaborating, edit conflicts may still occur. It is recommended to commit small changes at a time to a document branch to avoid conflicts.

Changing document properties

There are two types of document properties, built-in properties, and custom properties. To change any of the document properties:

1. Click on the Info button on the Home tab of the toolbar

2. The following built in properties can be changed

   Title: the document title of the current or staged commit

   Revision: the document revision of the current or staged commit

   Clause prefix: the clause prefix of the current or staged commit

Clause prefix parameters

Parameter	Description
number	the formatted number assigned to the document
revision	the revision property of the current or staged commit

Custom properties

Custom string properties can be created.

Adding a new sheet

Unlike other requirement editors, V-Raptor breaks document sections up into sheets. Additional sheets can be added where sections are logically different, for example document appendicies. Each sheet has it's own columns and clauses. As the columns can be unique to each sheet, clauses cannot be moved between sheets.

New documents will be created from a blank template which does not include a default sheet. To add a new sheet:

1. From the Home tab on the toolbar, click the Insert icon

   

2. From the drop down menu, click the Insert sheet option

   

3. A new sheet will be added to the document

   You can change the sheet name from the sheet properties

Sheets may also be added by clicking the + button next to the sheet tabs on the bottom of the document editor.

The new sheet will include a body column.

Sheet properties

1. Click either the id or number column headers to de-select any selected column, clause, or field.

2. From the View tab on the toolbar, click the Properties icon

3. The following properties can be changed

   • Name

     The unique name of the sheet

   • View style

     Style options when exported to DOCX

4. The following properties are for information only

   • Staged by, the user who staged the latest change
   • Staged at, when the latest change was made
   • Committed by, the user who committed the last change
   • Committed at, when the last change was committed

Adding a new column

Each sheet has it's own set of columns. To add a new column:

1. From the Home tab on the boolbar, click the Insert icon

   

2. From the drop down menu, click the Insert column option

   

3. A new column will be added to the current sheet

   You can change the column name from the column properties.

Column properties

1. Click on the column header you want to view properties for

2. From the View tab on the toolbar, click the Properties icon

3. The following properties can be changed

   • Name

     The unique name of the column

   • Description

     A description can be provided

   • Width

     The width of the column in pixels

4. The following properties are for information only

   • Staged by, the user who staged the latest change
   • Staged at, when the latest change was made
   • Committed by, the user who committed the last change
   • Committed at, when the last change was committed

Adding a new clause

Clauses can either be added at the end of a sheet, after a selected clause, or below a selected clause.

1. From the Home tab on the boolbar, click the Insert icon

   

2. From the drop down menu, click one of Insert clause after or Insert clause below options

   

3. A new clause will be added to the current sheet

Clauses can also be added by pressing the arrow down ↓ key with the last clause in a sheet selected.

Clause properties

1. Click on the clause id or clause number for the clause you want to view the properties for

2. From the View tab on the toolbar, click the Properties icon

3. The following properties can be changed

   • Prefix

     A string that is prefixed to the sequential clause id

   • Outgoing links

     Outgoing links can be deleted

4. The following properties are for information only

   • Incoming links
   • Staged by, the user who staged the latest change
   • Staged at, when the latest change was made
   • Committed by, the user who committed the last change
   • Committed at, when the last change was committed