Guide Adding Volume 1 landing page text to brt pg repo

[aszasz]

I will let this pull request open (without merging it), until we have landing pages to all volumes.

I am not sure what is best:

• have one file to each landing page text, or
• have the text for the landing page directly in the file the-guide.src

@dcpaschall : what seems easier for you?

[dcpaschall]

I think it depends on how the editing process can be done. Let's say I have all the volume texts in different files labeled accordingly, which are reference by the-guide.src. If I want to edit one of the volumes, could I simply edit the individual text file it is in and then refresh the-guide.src for it to take into account the changes made? Or are there more steps?

Also, it might be clearer to have them all in one document, the-guide.src because then when it is updated and we look at the changes, we can see exactly the text that has been added or changed, rather than a filename that represents the changes. Because with a filename, you would need to open up more documents to check on the changes. However, it is still hard for me to say one way or another having only limited experience so far with the software.

[jonasmalacofilho]

Actually, there wouldn't be any need to touch the-guide.src unless you had added or renamed a child (file).

In terms of analyzing diffs between versions (commits, branches or pull requests), both the command line git and the GitHub website show all changed (or new) files, so either way of organizing it would yield functionally equal results.

---

I would recommend that the choice be made based on what makes it easier to read or modify the content, not diffs. Practically speaking, splitting the content into multiple files makes it easier to read parts of the document, but that in excess can make working on the source quite tedious.

A rule of thumb could be to only defer content to a child file when, on average, that content has less than 2 or 3 paragraphs. This is similar to the reasoning used when we initially proposed that each section should live in a different file.

Alternatively, there could be a purely conceptual division, where a new file should only be created if the content within it could be read and modified as a reasonably independent unit from the rest; this would have the effect of making the small and less technical chapters single files.

Although the two methods are nothing more than examples, they would both result, at least for now, in having the landing pages in the root the-guide.src, together with the \volume and \include directives for each volume.