docs table of contents is cluttered #1802
Comments
|
Having 12 items in toc is way less of a problem than artificially putting stuff into sections where they do not belong. Like putting "changelog" under "support" or "license" under "development", for example. In case it would show only the first level of toc entries, people would have to uncollapse all items just to find stuff at places where they are not suppose to be. |
|
i do believe license belongs in development: the license is mentionned in the README and the program output, so the "user" case is covered there. the whole license detail is more relevant for developers wanting to contirbute or reuse code. as for changelog, i think it's relevant for the support section because it clearly shows which changes happened recently that may be relevant to support questions. regarding the uncollapsing, keep in mind that the full table of contents is also visible in the frontpage of the docs. as things stand, i think the list is too long and complex. but regardless, the point of this change is not just to change the big headings, but also refactor the documentation within. and while I welcome critical comments about the suggestions, constructive changes would be welcome as well - or you are saying that all the changes I suggest above are irrelevant and everything is fine with the current structure? |
|
actually, nevermind: i don't really want to argue about this. it was just a suggestion, which I thought was welcome because of @enkore's comment in the other issue... |
Usage & Limitations Security Common issues Miscellaneous (only three items, two fork-related) Note: This does not change any links to FAQ items.
|
Partly fixed by PR linked above. Thus: closing. |
first mentionned here: #1798 (comment)
this is an attempt at identifying those issues more clearly and restructure the documentation.
right now, we have this structure overall structure:
That list is too long (12 items). It would be better to reduce that to a more reasonable number, like 7-8 items. Note that a bit of restructuring has been done in the PDF document in #1796 but the table of contents there is still way too long.
I would recommend the following structure instead:
Note how we move Deployment within Usage, the FAQ, Resources and Changelog within Support, and authors, licenses and internals into a development section.
I would also move a bunch of stuff from the quick start into the Usage section, hence the "Manuals" section that would hold the manpages separately.
If you look in the current detailed listing (I removed some subtitles for clarity):
[...]
[...]
... you can see that certain documents are badly structured in themselves. For example, the Install page is well structured: it has 4 clear headings and subheadings that represent a basic decision tree on how to install Borg. The quickstart is less well structured: it is unclear why some items are there, or why they are ordered that way. It looks like it's the beginning of a more complete handbook, which is great, but it could have a better structure. The FAQ is the worst: it's just a random list of questions, without any structure...
It could look like this expanded:
[...]
[...]
Note the following changes:
I think this structure change is major, but would mean the documentation would be much more sustainable in the long term. For example, a lot of documentation could be added to the Handbook/Usage section without having to alter the structure too much.
Also note that, for larger sections, we can use the following directive to get a table of contents on top of the page, to make it easier to navigate:
This also works for sub-sections...
I'd be glad to have feedback on this. If necessary, I can shove this in a etherpad to ease collaboration on the structure.
Once a new structure is determined, I'd be happy to work on moving everything around. This should be done quickly and in one swoop, on both branches, so that things are consistent from now on.
#1796 would need to be merged first, of course. :)
The text was updated successfully, but these errors were encountered: