Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt
hiddentrue
nameLinear Documents on Requirement Yogi Cloud

You can now create requirements from your paragraphs with the Linear Document feature. You will be able to use public standards, and requirements from your customers. Discover how it works and get started!

Requirement Yogi for Confluence Cloud is able to parse paragraphs and linear documents.

Watch our quick tutorial:

...

...

What are “linear documents”?

Instead of writing requirements in tables, some companies write long documents with titles and paragraphs. We coined the term “Linear documents” to designate such documents. For example, all ISO standards are formatted as linear documents.

What your document looks like:

Image ModifiedImage Modified

Are “linear documents” a standard?

No. However, IEEE, ISO and many others use similar-looking documents:

Therefore we’ve specified “linear documents” below to unify the rules for our software.

Is there a template of linear documents?

There are no official templates, but there are examples:

Where are “linear documents” specified?

In the next section below.

Specifications for linear documents

Structure

The most expected structure is:

  • Foreword

  • Introduction

  • 1. Scope

  • 2. References

  • 3. Terms and definitions

    • A series of paragraphs, each preceded by the keyword as the subtitle for this paragraph.

  • 4. (First body title of the document)

    • 4.1 Subtitle

    • Paragraph

    • 4.1.1 Grand-child

    • Paragraph

    • 4.1.1.1 Fourth-level child

    • Paragraphs

  • A. Annex

  • Bibliography

How we parse

  • We’ll try to be as lenient as possible and give control to the user,

  • We’ll ignore the “Foreword” and “Introduction” etc.

  • We’ll put the prefix of the document before numbers like “4.1.1.1”, so the requirement key will be “DOC-4.1.1.1” and the text will be “Fourth-level child”,

  • We’ll consider DOC-4.1.1.1 as a child of DOC-4.1.1, and we will materialize it with a dependency, named @Section, to DOC-4.1.1. We’ll also materialize it with a plain text property named @Section (as well) which contains the titles:

    Code Block
    4. Top title
    4.1 Subtitle
    4.1.1 Grand-child
  • The last level of paragraphs are actual requirements. The intermediate levels only represent necessary boilerplate. To distinguish them and assist with searching, DOC-4.1.1.1 will have a property @Leaf = true.

Leniency

Since those documents are written by a variety of actors, we’ll support the following variations:

  • If titles are not numbered in the document, then we offer the option to add those numbers.

  • If titles are not numbered with actual numbers, we support uppercase and lowercase letters (A, a). We don’t support roman numbers for the moment (IV, iv).

  • If some titles are unimportant / irrelevant, then we offer the option to selectively ignore them.

  • If documents are spread out on several material pages (such as Confluence documents), then we offer to restart the numbering from a provided subsection.