Comments, notes & documentation
Last updated
Last updated
Clause9 provides many different ways to provide assistance towards the end-user, both in a Q&A and in the Assemble Document mode.
Every clause, card, question and predefined answer can have an associated short comment. Such short comment will be displayed in a popup-balloon.
Every clause can also have an reference to another online database (e.g., with case law or jurisprudence).
Instead of regular text, a short comment in a Q&A can also contain the address (URL) of an external website. This external website will then be shown at the right side of a Q&A.
In a Q&A, you can insert dedicated comments and warnings, as separate visual elements in the questionnaire.
Every clause, card, question and predefine can also be associated with a separate memo file. Such memo files can contain multiple paragraphs — or even multiple pages — of in-depth documentation.
Short comments can be added to both individual clauses and to a Q&A’s cards, questions and predefined answers.
You can also add short comments to a Document or Binder itself, which can be useful if you want to provide comments about the Document/Binder in general. Note however that these Document/Binder-level short comments will not be exported in any way.
To guide end-users when completing a questionnaire, you can attach a subtle help text to a question and predefined answer. This text will deliberately not be shown permanently: the end-user must hover above the question-mark icon in order to see the help text.
To attach such help text:
to a question, click on the question’s options, and insert your text within the “Help text”:
The comment will then show up as a question mark next to the question:
to a predefined answer, click on the question mark to the right of the predefine answer:
The comment will then show up next to the predefined answer:
Tip: the help text can include placeholders, which can then be dynamically replaced by other text. To do so, use ?PLACEHOLDER in the text, and insert a Change placeholder change to change the placeholder to something else (e.g., the answer to a certain question).
Tip: if the help text is merely intended to warn the user about the unit of measurement (i.e., that the answer should be assumed to be a percentage, or expressed in work days instead of calendar days, or provide a certain number of centimeters), you may instead want to use the suffix option of each question.
Clause comments are ideal to insert short notes about a certain clause — e.g. the source of the clause, some warnings on how to (not) use the clause, or perhaps short references to case law or legal doctrine about this clause.
When clause comments are available, a small information-icon will show up to the left of the clause:
In a Q&A, the information-icons are not visible by default. You will have to enable them by inserting a “Change various Q&A options” change, suboption “Show short comments attached to clauses?”. (As always, you can subject such changes to conditions, e.g. to only show the information-icons for some types of users).
To insert a short comment in a clause, open the clause for editing and show the Notes subpane (first click on the + more button).
Next, click on “Short comment”:
Finally, click on any of the available languages and start typing to actually insert the comment.
If “Never export” is checked, the comment will never be exported to MS Word / PDF. This allows you to selectively skip certain comments from ending up in the DOCX/PDF files.
When exported, clause comment (except those for which “Never export” was checked) will show up as popup balloons in MS Word:
However, this export must be explicitly enabled:
In Assemble Document, you have to click the wrench-icon in the toolbar, and check “export comments”.
In a Q&A, you have to insert a “Change the save / export settings” change, and enable the “Export comments” option. (You may want to subject this change to a condition, or couple it to a question in the questionnaire, to define the situations in which the comments should (not) be exported).
For each clause, you can insert one or more references to separate (legal) knowledge bases — e.g., containing in-depth discussions in legal doctrine, or case law about the contents of the clause, or perhaps official websites.
To insert such a reference, open the clause for editing and show the Notes subpane (first click on the + more button).
Next, click on “External link”:
These references will show up as (the last part of) a clause comment, and will be exported as such. See the section above on clause comments to learn how to enable/disable their visibility, and how to export them to MS Word.
Instead of a simple text balloon, you can also show external websites or PDF files, simply by inserting the URL of that website or PDF file into the help box of a card, question or predefined answer. The contents will then be shown on the right side of the browser window when the user clicks the question-mark icon. For example, when setting the help-text of the “First Name” to https://help.clause9.com/assemble-document/focus-mode, the following would be shown:
Please be aware that, for security (anti-spoofing) reasons, many websites will refuse to be shown inside another website (i.e., technically speaking, within an “IFRAME”). You should check with the webmaster of the target website if the website refuses to be shown at the right side.
Instead of using a help text or external website / PDF, you can also insert a comment or warning (which are separate types of “questions”). Unlike the help texts, comments and warnings can be subjected to conditions on when they should be shown — but if these conditions are met, they will be constantly visible on the screen.
To insert a comment or warning block, simply insert a question of type “Comment” or “Warning”. The difference between these two is the color displayed towards the user:
Memo files allow you to centralise your comments/documentation, to foster reuse across different clauses and Q&As. They are intended for multi-paragraph comments, or even multiple pages of in-depth documentation about a certain subject — even accompanied by subtitles and tables if you want.
A memo file is a separate type of file, which you can create in Browse files:
As is the case with any file, you can assign a name to a memo. Please note that this filename will show up on the screen towards the end-user.
The most important setting in this file is the “memo” pane, in which you can then insert formatted text, if preferred in multiple languages.
This editor works in a similar way as most other editors you can find online. A few interesting notes:
To attach a memo file to a clause, show the Notes pane of the clause editor (you may have to click on the + More… button).
Next, click on Link to memo:
Next, you will have to select the memo file you want to attach to the clause.
Note that you can attach multiple memo files to a single clause. Also, you can attach a single memo file to multiple clauses (and/or multiple cards/questions/predefined answers). The underlying idea is that you should centralise your knowledge, and reuse it as much as possible across your entire library.
If “Never export” is checked, the contents of the memo will never be exported to MS Word / PDF. This allows you to selectively skip certain memos from ending up in the DOCX/PDF files.
You can also add memos to a Document or Binder itself, which can be useful if you want to provide extensive comments about the Document/Binder in general. Note however that these Document/Binder-level memos will not be exported in any way.
For performance reasons, memo files (which can easily contain hundreds of kilobytes) are deliberately not loaded together with the document/binder/Q&A they are associated with. Instead, they will be separately fetched from the server at the moment the user clicks on a button to read the memo.
Unlike other content that is part of a document/binder/Q&A (which is always loaded in one batch from the server, so that no separate security checks are performed beyond having the right to receive the document/binder/Q&A), you should be aware that the user should have the right to read the memo. If, for example, a Q&A is stored in a group library, but the memo files are stored in various personal folders, then users will receive errors when trying to read the memos.
To attach a memo file to a question, click on the green “+ Memo” button in the question’s options, and subsequently select the memo file.
To attach a memo file to a question, click on the green “+ Memo” button in the card’s options, and subsequently select the memo file.
To attach a memo file to a predefined answer, click on the question mark to the right of the predefined answer. Next, click on the green “+ Memo” button and select the memo file.
In Assemble Document, memo files attached to a clause show up as (part of a) clause comment, under the blue information-icon. (In Assemble Document, this visibility is enabled by default. The comments can be hidden, however, through the “…” menu at the right — see submenu Visibility).
When you then click on the title or icon of the memo file, the memo will be shown in the right part of the screen.
In a Q&A, the information-icons are not visible by default. You will have to enable them by inserting a “Change various Q&A options” change, suboption “Show short comments attached to clauses?”. (As always, you can subject such changes to conditions, e.g. to only show the information-icons for some types of users).
If a memo file is attached to card, question or predefined answer, then it will show up as a separate icon on which the user can click. If clicked, the memo is then shown at the right bottom side of the screen:
When exported, memo files end up as footnotes in the PDF / DOCX file. (The reason is that these memo files can be multiple paragraphs long and/or include tables/subtitles/etc., which is not suitable for comment popup-balloons.)
However, exporting of comments should be enabled first. Please see exporting comments above.
In Assemble Document, this visibility is enabled by default. The comments can be hidden, however, through the menu at the right (see submenu Visibility).