View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0000747||bareos-core||[All Projects] documentation||public||2016-12-30 17:33||2017-06-08 13:36|
|Fixed in Version|
|Summary||0000747: Consider moving away from one long page|
|Description||The 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 Information||MkDocs http://www.mkdocs.org/ (I'm not linked)|
Example 1: https://gluster.readthedocs.io/en/latest/
Example 2: https://docs.syncthing.net/
|Tags||No tags attached.|
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.
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.
|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.|