Factor reference material out of documentation how-tos #942

New issue

Closed

opened 2024-11-18 23:24:25 +00:00 by witten · 1 comment

witten commented

2024-11-18 23:24:25 +00:00

Owner

What I'd like to do and why

The borgmatic how-to documentation has grown organically over time, accreting a fair amount of reference-oriented material interspersed within the how-to content. This makes it difficult to find the right reference material when you need to know about how a particular feature works. It also makes it difficult to discover features to begin with, because the docs are not oriented in terms of features but rather use cases.

Additionally, much of the existing reference material feels shoehorned into the how-to docs. For instance, a page about passwords contains docs about the environment variable feature (which can be used for more than passwords), and the page about databases contains the docs about borgmatic's runtime directory (which applies to more than just databases).

So for this ticket, do a holistic pass over all the how-to documentation, factoring out material into separate reference docs as appropriate.

Other notes / implementation ideas

This will entail figuring out:

The best way to structure/organize the reference material.
How to mention the reference material in the how-to docs so that the how-to docs still flow, make sense, and remain useful.
What to do, if anything, about broken links to individual how-to sections that may be moving out. E.g., the NEWS file, release notes, and even ticket comments are full of links to how-to documentation sections.

As part of this work on reference docs, consider documenting all of the files and directories that borgmatic uses, like how Borg does. (See "directories and files.")

### What I'd like to do and why The borgmatic [how-to documentation](https://torsion.org/borgmatic/) has grown organically over time, accreting a fair amount of reference-oriented material interspersed within the how-to content. This makes it difficult to find the right reference material when you need to know about how a particular feature works. It also makes it difficult to discover features to begin with, because the docs are not oriented in terms of features but rather use cases. Additionally, much of the existing reference material feels shoehorned into the how-to docs. For instance, a page about passwords contains docs about the environment variable feature (which can be used for more than passwords), and the page about databases contains the docs about borgmatic's runtime directory (which applies to more than just databases). So for this ticket, do a holistic pass over all the how-to documentation, factoring out material into separate reference docs as appropriate. ### Other notes / implementation ideas This will entail figuring out: 1. The best way to structure/organize the reference material. 2. How to mention the reference material in the how-to docs so that the how-to docs still flow, make sense, and remain useful. 3. What to do, if anything, about broken links to individual how-to sections that may be moving out. E.g., the NEWS file, release notes, and even ticket comments are full of links to how-to documentation sections. As part of this work on reference docs, consider documenting all of the files and directories that borgmatic uses, like how [Borg does](https://borgbackup.readthedocs.io/en/1.4.0/usage/general.html). (See "directories and files.")

witten referenced this issue

2024-11-18 23:25:34 +00:00

Update the logic that probes for the borgmatic streaming database dump, bootstrap metadata, and check state directories (#934). #937

witten referenced this issue

2025-02-25 22:00:35 +00:00

Skip all checks doesn't work. #1008

witten referenced this issue

2025-03-17 17:27:34 +00:00

Run before_backup once (with multiple repositories) #790

witten referenced this issue

2025-09-12 16:23:23 +00:00

manifest.json missing with certain exclude patterns #1122

witten referenced this issue

2025-10-09 21:11:04 +00:00

Restore error for multiple configurations #1160