Linear documents: Manage requirements outside of tables

 

Requirement Yogi for Confluence Cloud is able to parse paragraphs and linear documents. Watch our quick tutorial:

https://www.youtube.com/watch?v=uAF5Zi08gOo

 

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:

 

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:

    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.