Linear documents: Manage requirements outside of tables

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:

• ISO/IEC publishes their directives for document formats: https://www.iso.org/directives-and-policies.html

• IEEE publishes a preferred style for proposed IEEE standards, the IEEE SA Standards Style Manual.

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:

• ISO publishes a Word template on this page: https://www.iso.org/iso-templates.html

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

  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.