# 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**](/clauses/clause-structure.md#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](/clauses/advanced-multi-language-features.md#reusing-contents) `// 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 | <p>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.</p><p>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.)</p> |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.clause9.com/misc/creating-high-quality-documents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.