Checklist: 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 folderAvoid 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.


Use internal commentsComplex clauses may require internal comments to clarify towards other clause authors why you took a certain approach.
Reuse contents across languagesIf 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.


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.



Include labelsInclude 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.


Don’t hardcode text snippetsAvoid “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&AsDatafields 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.



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.)
Was this article helpful?
Checklist: common pitfalls