What are the advantages of using multiple files for an AsciiDoc document?

Question

We are considering using Asciidoc to create a users guide, and we were going to just version a single file on github.

We see, however, that established projects like ProGit (https://github.com/progit/progit2/tree/master/book), although also producing a single document, split the Asciidoc into multiple files.

What are the advantages of splitting a logical doc into multiple files?

Answer 1

I think the biggest advantages to using multiple docs are organizational and mental. Say you have document for each section, it's much easier to find and fix or add to a section if it's in its own document. It's also easier to mentally consume and think about when you open smaller documents than larger ones. If you open a document and the scroll bar starts getting smaller and smaller you start to think how long it'll take to find you you need to change, if it's worth making the change and how long it will take to load. Of course these are all subjective and maybe some people don't have that problem.

Another good reason for multiple documents is if at some future time you decide to split off each section / chapter it is easier to start with multiple documents and include them into one big one than it is to try and chop it up afterwards.

Along with the organizational issue, if you have multiple people working on a document it's easier to see changes in a smaller document than it is one large document.

Answer 2

It is great when you are working with multiple writers or with a very large book and store the content in a version control system like GitHub. Then writers can own and edit content without having to merging their changes into a single huge document.

Multiple documents can sometimes take the place of content tagging. For example, if there is various content that may or may not make it into a release version of your final document, it is easier to comment out the line that refers to an unfinished chapter (in a book file of chapters) than to try and tag the specific conent and write an output script to filter that.

If you are a single writer and will not be reusing the content you will probably find it easier to keep everything in one place.

Answer 3

The same question goes for any other programming system.

Advantages of one big file:

• searching for a known term is easier. E.g. /# header in Vim
• order of the text is implied without IDs. For smaller files, you either need a TOC in some file, or to number each file as 01_, etc.

Advantages of small files:

• browsing sections is easier. E.g.: ls or looking at the a hand made TOC. Possible to overcome with a custom editor outline feature.
• only recompile the files that changed. E.g.: a.c -> a.o -> a.exe. Only the linker part must happen every time, but that is cheaper.
• smaller file load time
• if you want to find something within a section, you can just hit Ctrl + F and type, and it won't take you out of that file. In a big file, it might, and it takes some effort / tooling to say if you have left the section.
• it is easier to jump to a given section once you know it's name. In Vim for example, you can :b something and tab autocomplete the file name. If the section is just a header inside a big file, you can't do that.