If you write a documentation that is 30 kB or larger you should split it up into different parts which 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.
Even keep multi-langual documentations in mind. If you keep – like we do – e.g. all German texts in files using the extension .de and all English texts in .en files, you will be able to keep your localizations tidied up and can e.g. create copies from your .en files for e.g. French, change the extensions of the copies into .fr and hand out these files to your French localizer.
Furthermore you can test or convert only some parts of the documentation. Maybe 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.