search

zynaddsubfx / user-manual

User manual (this may or may not get merged into zynaddsubfx/zynaddsubfx's doc dir)
30 stars 10 forks source link

Publishing via ReadTheDocs.org? #1

Closed unfa closed 6 years ago

unfa commented 6 years ago

I wonder if you've thought about the final distribution platform for this manual.

I personally really like ReadTheDocs for a few reasons - one major being the fact that any documentation there can be easily downloaded in multiple formats. Being able to quickly get a PDF offline version is a huge benefit in my eyes. I tend to read manuals while on the go, on a mobile device, often without Internet access.

For example Kdenlive hosts is manual only on its own site, and getting an offline usable version was beyond my Linux powers. I was unable to mirror that manual, which greatly reduced it's usability for me.

On the other hand - Natron, Zone Minder, Animation Nodes, Godot all host their manuals on ReadTheDocs, and I consider that a great feature and a real boost in learning the software.

https://readthedocs.org

What do you think?

fundamental commented 6 years ago

At the moment readthedocs does not support asciidoc which is the current format of existing documentation and the future target for the user manual.

one major being the fact that any documentation there can be easily downloaded in multiple formats.

Currently the zyn docs are used for manpage generation, html generation, chunked html generation, and pdf generation. asciidoc has a variety of options with regards to outputs and can be easily restyled.

quickly get a PDF offline version

In ~5 minutes I was able to generate http://fundamental-code.com/tmp/zynaddsubfx.pdf

on a mobile device

Better yet, there's even .epub support with asciidoc if that becomes of interest down the line.

What do you think?

Read the docs has a lot of nice properties, however I don't think it's the right solution for this particular project.

unfa commented 6 years ago

I see. In such case I think providing PDF and EPUB downloads would be a good idea. Not being able to read the manuals offline can be frustrating.

fundamental commented 6 years ago

Understood. Down the line some form of continious integration could be added to take each commit of the manual and upload to zyn's website a new html and pdf version (at a minimum).