Bareos Bug Tracker
Bareos Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0000747bareos-core[All Projects] documentationpublic2016-12-30 17:332017-06-08 13:36
Reportermichelv 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityalways
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version16.4.1 
Target VersionFixed in Version 
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.
bareos-master: impact
bareos-master: action
bareos-17.2: impact
bareos-17.2: action
bareos-16.2: impact
bareos-16.2: action
bareos-15.2: impact
bareos-15.2: action
bareos-14.2: impact
bareos-14.2: action
bareos-13.2: impact
bareos-13.2: action
bareos-12.4: impact
bareos-12.4: action
Attached Files

- Relationships

-  Notes
(0002495)
joergs (administrator)
2017-01-03 13:09

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.
(0002496)
michelv (reporter)
2017-01-03 18:02

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.
(0002529)
joergs (administrator)
2017-01-25 14:41

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.

- 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


Copyright © 2000 - 2017 MantisBT Team
Powered by Mantis Bugtracker