Embedding questions into a document

Rationale

Clause9’s standard approach is to show all questions at the left side, so that — except for the changes Allow user to choose alternative clause and Allow user to disable clause, which show icons to directly delete or replace specific clauses — end-users can rest confident that they can limit themselves to looking at the left side. In other words, the questions and answers at the left side act as the single source of truth.

Even so, keeping (almost) everything at the left side occasionally has some drawbacks. In the following situations, it could be useful to allow end-users to directly interact with the document at the right side:

• Clauses that use datafields in conditions. Such datafields will not normally “show up” as yellow placeholders in the contract text, so users cannot click on a placeholder to navigate to the associated question. In such scenario, it can be useful to repeat some questions immediately above or below the clause itself, to allow the user to fine-tune the clause.

• Datafields regarding small details. Often, because it concerns such a small detail regarding a specific clause, you end up with long or cumbersome questions, because the question needs to sketch the context of where this tiny detail is relevant. Conversely, if the datafield gets immediately inserted into the clause text itself, any legal expert would immediately know what this is about.

• Embedding comments or warnings in the middle of the contract text. Such comments/warnings will not end up in the exported PDF/DOCX file.

As described below, we therefore also provide you with the possibility to embed questions and datafields directly into the document at the right-side.

Drawbacks

Despite its advantages, you should also be aware of the drawbacks of directly embedding questions into the right-side:

• This undermines the “single source of truth”, i.e. an end-user’s trust that he should only look at the left side to cover everything.

• Contracts can easily get very long, and you do not want to force your users to scroll through the entire contract text to “hunt” for datafields that are still missing.

• In many situations, your (non-legal) end-users will not be interested in — or even not understand — the contract text. You do not want to force users to read the contract text.

For these reasons, the embedding is an opt-in approach, so we continue to recommend to apply the traditional approach, and only apply this feature where useful. .

Moreover, you can dynamically toggle the visibility of all this embedding stuff. Through a simple condition on the change-set, you could, for example, specify that only advanced / legal users should see the embeddings, while all the basic/nonlegal users would get the traditional view. We think this will solve most concerns about the “single source of truth” and forcing users to scroll through the text at the right side.

Functioning

In the Embedding part of the Interaction section of a question’s options, you can now specify the following settings:

• Don’t embed. This is the default setting, i.e. a question will only show up at the left side.

• Above/below clause. Means that a question will always show up a the right side, above/below its associated clause.

• Above/below clause, if toggled. Means that a question will only show up at the right side if the triangle is toggled.

• Within clause. Means that a datafield will be directly inserted into the text, everywhere it shows up as part of the body text (i.e., not as part of a condition, except if you would insert an exclamation mark — e.g., #condition^!datafield). Note that this means that the datafield will show up in every clause that uses that datafield, so not only within the (explicitly or implicitly) linked clause.

The associated clause of a question can be specified through the Link to clause setting of the Interaction section of a question’s options. Essentially, a question & the first instance of a clause using the datafield linked to that question will be implicitly linked, except when you explicitly point towards another clause.

Example of embedding above a clause:

Example of embedding below a clause, if not yet toggled:

Example of embedding below a clause, in toggled state:

Example of embedding within a clause: