December 16, 2021

How to write longer technical documents

 

There is some sort of mystery available about how to create longer documents and especially academic books. On the first look the problem is easy to manage because there are word processing tools like MS-Word available plus dedicated publishing tools like Framemaker. The problem is that most authors are not interested in using a certain software but they want to know in general how to write a document.
The first thing which is important to know that writing a document has nothing to do with formatting it. Formatting a document can be realized by pressing the CTRL+A key to select the document and then select a font in the menu. So the formatting task is the easier one. The more serious question is how to create the text. This is done with a software tool called outline editor. Without an outline editor it is not possible to write longer technical documents.
Let us take a closer look how the existing programs are working. Software used for writing books are MS-Word, framemaker, libreoffice, latex, lyx and many other. What all these programs have built in is an outline editor. The interesting situation is, that this feature isn't mentioned in the handbook and most authors doesn't know what an outline editor is. But they are using this mode all the time. Let me give an example.
The famous program texniccenter is an IDE for the LaTeX program and according to the amount of documention, texniccenter is used to write papers in the reality. There is a single feature available in the program which is the ability to manage a pane on the left side. This pane can be used to use texniccenter in the outline mode. That means, the user can create notes or longer text and order them in a hierarchical fashion.
The interesting situation that other state of the art programs like MS-Word, lyx or emacs have s similar built in feature. Writing a text means basiically to type in the text into an outline editor. How this editor is called doesn't take matter. And it is also not very important if it is using LaTeX or not. The only thing which is simportant that some sort of outline editor is available. Let us take a look into a seldom mentioned software available as opensource: Cherrytree.
Cherrytree is a normal outline editor without additional formatting options. it can be seen as a tripped down version of Lyx. Lyx needs around 10 GB on the harddrive which includes the TeX back end, but cherrytree works fine with 10 MB space. According to the self description in the debian repository, “CherryTree is a hierarchical note taking application.” And yes the program is more than suited to created longer technical documents.
The interesting fact is, that Cherrytree doesn't belongs to the categories of word processing software. It is not a WYSIWYG software like Word, and it is not LaTeX clone for text based markup. At the same time, the program is the core component of a technical authoring software.