If you write a documentation that is 30 kB or larger you should split up it into different parts that you can merge with !include.
By splitting up the documentation you are e.g. enabled to restructure it by simply moving one line of your main source file. If your documentation is part of one file you have to move blocks of text to restructure it.
Another advantage is that you can find specific chapters more quickly if you write them to files that you name like this chapter.
Denken Sie auch an mehrsprachige Dokumentationen. Wenn Sie – wie wir es tun – z.B. alle deutschen Texte in Dateien mit der Endung .de und alle englischen Texte in .en-Dateien pflegen, behalten Sie noch besseren Überblick über die einzelnen Sprachen und können z.B. aus den .en-Dateien rasch Kopien für z.B. Französisch erstellen, die Datei-Suffixe der Kopien in .fr ändern und dem französischen Übersetzer nur diese Dateien geben.
Furthermore you can test or convert only some parts of the documentation. My be you have a documentation with five chapters. Write a preamble file, a main file and five files that contain the chapters:
[main.u] !include header.ui !begin_document !maketitle !tableofcontents !include chapter1.ui !include chapter2.ui !include chapter3.ui !include chapter4.ui !include chapter5.ui !end_document [header.ui] !docinfo [title] ... !docinfo [program] ... !docinfo [author] ... [chapter1.ui] !node Chapter 1 ... [chapter2.ui] !node Chapter 2 ... [etc.]
If you now want to convert a single chapter you simply edit another main file:
[ch5test.u] !include header.ui !begin_document !maketitle !tableofcontents !include chapter5.ui !end_document
If you use this method you will be able to find errors in a large documentation more quickly.
Just take a look at the source files of the UDO documentation if you want to know how to split up a large documentation. You can believe me that it would be hard work if all the text would be part of a single text file.