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.) |