` node. However, technical writers should apply the conref mechanism only for complete sentences or terms not intended for translation (e.g., company or product names). Otherwise, significant issues arise during [language translation](https://docs.redaction-technique.org/en/tech-writing-process/translation/).
> **Diagram: Sentence structure varies by language**
>
> Diagram showing the same conref segments assembled in a different order for two languages, illustrating why segment-level conref does not translate cleanly.
**Sentence structure varies by language.**
**Example**
If you set conref granularity at the segment level and define:
```xml
Click the
blue
arrow
```
You can then use:
```xml
.
```
to generate "Click the blue arrow."
To create a French version, you translate each segment in place:
```xml
Cliquez sur la
bleue
flèche
```
But the assembly order is fixed (click, blue, arrow), so it now yields "Cliquez sur la bleue flèche" — incorrect French, because the adjective *bleue* belongs after the noun *flèche*. The correct sentence, "Cliquez sur la flèche bleue," would need the segments assembled in a different order for this language.
Rearranging conref order per target language is impractical, so in the worst cases the only remedy is to drop segment-level conrefs entirely in the target language — a pitfall I’ve managed to avoid.
### Limit conref nesting
To facilitate DITA XML content maintenance and updates, technical writers should minimize excessive conref nesting. A single level (one conref within another) is generally manageable.
In the example below, source *conref* *see-admin-guide* includes target *conref* *admin-guide-title*:
**Example**
```xml
For further information, see the .
```
This level of complexity is navigable. But if *admin-guide-title* contains yet another target *conref*, the DITA XML becomes cumbersome (and you risk circular references). In theory the possible combinations are endless; in practice the problems multiply just as fast.
> **Diagram: Multi-level conref nesting is risky**
>
> Diagram showing three levels of conref nesting, one conref pointing to a conref pointing to another conref.
**Multi-level conref nesting: risky!**
Summary:
- Multiple source *conref* nesting is viable but impacts file readability.
- Source and target *conref* nesting is often unmanageable.
- Target *conref* cannot nest; top-level *conref* overrules lower-level values.
### Maximize conref use to reduce costs
> **Tip**
>
> Leveraging conref enables DITA XML technical writers to significantly cut costs and publishing times, especially in multilingual contexts — an important consideration when [choosing formats and tools](https://docs.redaction-technique.org/en/costs/formats-and-tools/).
*Task* sections, due to their nature, often see higher content reuse than *concept* or *reference* sections.
> **Diagram: Conrefs modularize small information blocks**
**Conrefs modularize small information blocks.**
A common pattern is to write only the unique titles and pull in everything else with *conref*.
**Example**
```xml
Display trends
```
Only the plain text content - not the surrounding markup - requires translation. Translating this type of DITA XML content involves translating just the title and the full set of source *conref*. Translators, lacking context for these discrete information units, require support. Ideally, translators work onsite, accessing both the technical writer and product designers.
> **Note**
>
> This is not a constraint solely from advanced content modularization. As a translation school graduate - trained in the *triangle of meaning* principle, whereby the translator must understand the source text well enough to reformulate it in the target language rather than transcribing words one by one - and with several years of technical translation experience, I've found that every successful project relies on collaboration among designers, writers, and translators.
You can also apply this to structural elements, like table headings, to present information consistently at lower costs without specialization.
### Protect confidential information
> **Tip**
>
> The robust conref mechanism in DITA XML can also protect sensitive information. A technical writer can hide information within the source code.
Consider a scenario where a file with confidential information requires translation, but cannot be accessed by the translator (due to client confidentiality clauses).
What can be done? The *ditaval* mechanism filters out information from the deliverables but not from the source files. Must you create separate source files for confidential and non-confidential information? That negates single-sourcing and content reuse - the very reasons for choosing DITA XML!
> **Diagram: Hiding confidential information from translators**
>
> Diagram showing a confidential source in language A split by translation into two branches, each filtered through ditaval, producing a language A deliverable that keeps the confidential information and a language B deliverable that excludes it.
**Hide confidential information from translators**
By placing confidential content in a separate file (e.g., `confidential.dita`) and setting conref with a filter key in the translatable file, you manage access. The translator processes only non-confidential text, and deliverables in the target language exclude confidential content, marked as conditional and explicitly excluded via the *ditaval* file during compilation.
## Provide targeted information with Ditaval conditional text
A ditaval file operates like 3D glasses: one lens masks one half of the information, the other lens the other half. Only the technical writer has complete information.
The information recipients have glasses showing either only left or right lens content. Though they see less, they access what they need without noise. This adheres to the minimalist principle "less is more."
> **Diagram: Conditional text filtering with ditaval**
>
> Diagram showing a source filtered by ditaval into two distinct targets, each receiving only the content selected for it.
**Conditional text with DITA XML**
The ditaval mechanism is based on binary logic: mark a block with an attribute and value, then include or exclude it in deliverables via a compile-time operand (default is inclusion without operand). This constitutes conditional text.
This mechanism negates the need for separate files for minor content variations, further reducing source content redundancy.
Combined filter keys (a logical AND) can be specified as space-separated values within an attribute such as product, audience, and so on.
**Example**
To profile information for both electricians and advanced users among these groups:
- Non-electricians
- Beginner electricians
- Expert electricians
Use the structure:
```xml
Bring the intensity below the lethal dose of 150mA.
```
> **Caution: Warning**
>
> A filter key placed incorrectly can cause a compilation error. A code block compliant with the unfiltered XSD DITA XML schema may not remain compliant once filtered.
**Example**
Correct before filtering:
```xml
Order
Description
```
After filtering, the result is:
```xml
```
According to the XSD schema, table headers require at least one row:
```xml
```
This filtered code is incorrect and leads to compilation failure.
## Related articles
- [Case studies in using DITA XML](https://docs.redaction-technique.org/en/formats/dita-xml-case-studies/)
- [From document to modular document base](https://docs.redaction-technique.org/en/formats/modular-documentation/)
- [Too complex a document architecture?](https://docs.redaction-technique.org/en/formats/document-architecture-complexity/)
- [DITA XML and XSL-FO tutorials](https://docs.redaction-technique.org/en/tutorials/dita-xml-xsl-fo-tutorials/)
---
Source: https://docs.redaction-technique.org/en/formats/nufirewall-case-study/