View Issue Details

IDProjectCategoryView StatusLast Update
0000747bareos-coredocumentationpublic2021-06-09 17:44
Reportermichelv Assigned Toarogge  
PrioritynormalSeverityfeatureReproducibilityalways
Status resolvedResolutionfixed 
Product Version16.4.1 
Summary0000747: Consider moving away from one long page
DescriptionThe whole manual is now in one document/page, making it very hard to navigate and find parts easily.
A lot of project use easy to read documentation build with tools such as MkDocs. I would argue it would help the project to transfer the one page document to a layout with parts.
Additional InformationMkDocs http://www.mkdocs.org/ (I'm not linked)
Example 1: https://gluster.readthedocs.io/en/latest/
Example 2: https://docs.syncthing.net/
TagsNo tags attached.

Activities

joergs

joergs

2017-01-03 13:09

developer   ~0002495

Bareos Main Manual:

While I fully agree, that there is a lot of room for improvements in the Bareos manual, and we also discussed changing from the current LaTex backend to some other format, I don't see changing to this mkdocs Mark Down format soon.
That would require be a lot of effort. Also some features would get lost.
Enhancing it by additionally host it as separate sections could be done. This is already on the TODO list. However, it fear this will not greatly improve readability.

Bareos Developer Guide:
The Bareos Developer Guide (http://doc.bareos.org/master/html/bareos-developer-guide.html) has been migrated to Mark Down a while ago. This could be enhanced by mkdocs.
michelv

michelv

2017-01-03 18:02

reporter   ~0002496

Of course the way of writing is up to you.
From latex to MD can be done by tools, eg http://pandoc.org/demos.html

Another consideration might be to make it easier to help out with docs.
I personally have seen that it can work nicely at github, where people can relatively easily add/adjust with pull requests to the md files.
joergs

joergs

2017-01-25 14:41

developer   ~0002529

We used pandoc to migrate the Developer Guide from Latex to Mark Down. However, even this relatively simple document causes a lot of trouble. So this is not an option for the Bareos Main Manual.
arogge

arogge

2021-06-09 17:44

manager   ~0004147

The documentation has been migrated to ReST and is now split into smaller individual files.
I guess that fixes the issue. If it doesn't and you have additional requirements, feel free to reopen.

Thank you!

Issue History

Date Modified Username Field Change
2016-12-30 17:33 michelv New Issue
2017-01-03 13:09 joergs Note Added: 0002495
2017-01-03 18:02 michelv Note Added: 0002496
2017-01-25 14:41 joergs Note Added: 0002529
2017-06-08 13:36 joergs Status new => acknowledged
2021-06-09 17:44 arogge Assigned To => arogge
2021-06-09 17:44 arogge Status acknowledged => resolved
2021-06-09 17:44 arogge Resolution open => fixed
2021-06-09 17:44 arogge Note Added: 0004147