Creating high-quality documents

This page provides a checklist for users who want to lift their automated documents to the next level — creating a truly top-notch experience for end-users.

Warning: work in progress!

Organisation of files

Put files of the same type in the same folder	Avoid having folders that contain a mix of snippets, clauses, documents, concepts etc. As a rule of thumb, every file type should have its own folder.

Clauses

Use internal comments	Complex clauses may require internal comments to clarify towards other clause authors why you took a certain approach.
Reuse contents across languages	If the contents of a clause is completely identical between different languages, then avoid copy/pasting that content. Instead, insert the content in one language (e.g. English), and repeat it using the special content-reuse code // English.

Lists

Wrap text-list datafields	Have you wrapped lists of texts datafields in @enumerate-and, @bullets-and, or similar functions? Otherwise they will get outputted as simple comma-separated lists.

Concepts

Datafields

Include labels	Include a separate label for each datafield whose name is not nice to read. For example, for a datafield commencement-date, include a label commencement date.

Miscellaneous

Don’t hardcode text snippets	Avoid “hard coding” snippets of text that you will use in conditions — such as names of countries or languages. This is particularly true in multi-lingual documents.

Assemble Documents

Check datafield assignments before transferring to Q&As	Datafields may have values assigned in the underlying Document/Binder, so that a Q&A using that Document/Binder will have those datafields filled in as default values. Check whether you did not inadvertently leave some datafields values assigned from any testing you performed.

Q&A

Answers

Mandatory?

By default, questions are not mandatory. Check which questions you want to make mandatory instead.

Pre-select a predefine

If you include predefined answers, then make sure that one of those predefined answers get pre-selected — even if your pre-selection may feel a bit arbitrary. A user may otherwise get confused when he selects a predefined answer, and the text preview at the right side does not get updated. (E.g., if you allow selecting A, B or C as predefined answers, and the associated clause will show A even when no answer has been selected, then the clause will not update when the user explicitly selects A.)