View Issue Details

IDProjectCategoryView StatusLast Update
0000747bareos-core[All Projects] documentationpublic2017-06-08 13:36
ReportermichelvAssigned To 
PrioritynormalSeverityfeatureReproducibilityalways
Status acknowledgedResolutionopen 
Product Version16.4.1 
Fixed 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-19.2: impact
bareos-19.2: action
bareos-18.2: impact
bareos-18.2: 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

Activities

joergs

joergs

2017-01-03 13:09

administrator   ~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

administrator   ~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.

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