#121 Issue closed: Create "final" documentation structure

Labels: documentation, discuss / RFC

dagwieers opened issue at 2012-06-25 19:30:

I am looking for feedback from users (and collaborators) regarding the documentation structure. The below structure is based on the current draft documentation. I would like to make sure the documentation tells a story (is consistent, entertaining and useful) and is balanced in its chapters.

It makes sense to start with an introduction explaining the project, how it was conceived and what it can do. Then tackle installation and configuration. Explain various scenarios (that we hopefully also test automatically). And then some appendices (monitoring, support, troubleshooting).

What I am struggling with is how the configuration section would work, there are various items that cannot be ordered and have similar importance. One option is to have a long alphabetical list of configuration options, another option is to look at a batch of options related to a certain topic, but that makes it harder for future improvements to not miss (or clean up) options.

And then there's a partly overlap between configuration options, and the use-cases/scenarios that explain the same options again. And I would like the layout configuration manual in there as well somewhere. Now it is listed as an appendix (and we have more appendices than actual chapters).

My aim, to make it easier to help out with documentation, or to find help, is to make a separate file of each chapter, which are included from the main documentation. In this form the different chapters can stand on their own from a packaged installation (even when not in HTML or PDF file), while with one large document it is harder to find what you are looking for (if there is no index). As soon as we have an acceptable structure defined, I can got and start making the individual chapters and collaboration on the documentation can begin.

Relax-and-Recover documentation

  • Introduction - Explain the project, what it can do and how it was conceived
    • Relax-and-Recover project
    • Features
    • Design concepts - original concept document
    • Use cases - example use-cases from #94
      • Transforming a system to use LUKS partitions
      • Recreate a system for optimal partition alignment
      • Transforming a system to move from SWRAID to HWRAID
      • Transforming a system to move from SWRAID to LVM mirroring
      • Recreate a system on a new RAID hardware backend (replace all disks to enlarge limited storage)
      • Create a single snapshot for offsite troubleshooting
  • Getting started
    • Software requirements
    • Limitations
    • Installation
      • From packages
      • From source
    • Paths and files
    • Quick demo
  • Configuration
    • Boot images
    • Transferring images
    • Backup
    • Boot-loader integration
  • Scenarios - includes the existing scenarios from the website and draft doc
  • Network storage
  • USB storage
  • Tape storage
  • Centralized storage
  • Integration
    • Monitoring
      • Nagios / Opsview
  • Layout configuration - @jhoekx layoutman document
  • Tips and Tricks
  • Tested configurations
  • Troubleshooting
    • "normal" mode
    • "rescue" mode

towster commented at 2012-07-12 22:23:

I am just starting out trying to use ReaR and I am finding the documentation to be the most frustrating part.
I think that the thing that would help me the most would be more examples of conf files for various implementations.
I know you are worried about changes in the conf with new releases. One way to mitigate that some would be to simply put the conf file examples in the build and you would simply need to cite the name of the example in the docs. Then the docs become more about how to use the application (which shouldnt change as much).

dagwieers commented at 2012-07-13 10:21:

We don't have these different conf files in the build as separate files, simply because all possible combinations is simply too large. Basically a configuration is combination of an OUTPUT method, a BACKUP method and the specific configuration of both (usually OUTPUT_URL and BACKUP_URL). That is it.

The documentation should explain the various options for both OUTPUT and BACKUP. If this was not clear from the documentation please provide us with patches/pull-requests to the documentation to improve it. Honestly, writing good documentation is much harder for us, as we know exactly how it works so we don't consider the obvious questions new users have.

So we need new users to tell us what they missed from the documentation, or to explain their confusions, rather than adding specific config files for specific cases. (Unless of course one config file would cover 80% of the cases, which in our case is not the case...)

dagwieers commented at 2012-07-24 21:16:

Implemented. Now we need to continue fixing #4 !

[Export of Github issue for rear/rear.]