Re-use guidelines can help simplify the practice of writing for
When writing in a DITA environment, at topic level rather than document
level, there are a few guidelines you can follow to make re-use easier by
adopting the following guidelines.
- Avoid the use of
"later" (such as in
"More information on the product limitations are discussed
later"). Those referenced topics may not be included in all collections, or
may be included in a different sequence.
- Don't use sequential numbers
in file names; rather, use descriptive names. (Use
ej20_engine_schematic.png rather than
- Avoid including branding in
- Avoid including context
within explanatory paragraphs or steps. For example, don't write
"The EJ20 engine of the
is naturally aspirated"; rather write
"The EJ20 engine is naturally aspirated".
contextual information to its own paragraph (or
context element, for task topics). In the EJ20 example
preceding, the information about what models of car use the EJ20, and other
information relevant to the association between EJ20 and
could be written into a separate paragraph. When the content needs to be
re-used in a differently badged product manual, that context paragraph can be
filtered out and the remaining non-contextual content re-used.