KDE's getting started page on documentation states:
KDE documentation is written in DocBook XML.
Historically, this was probably a good decision. Who does not remember that XML was so much easier to read, parse, and work with compared to binary or virtually any propitiatory file format?
KDE is aiming to bump its major version to 6. This might be a good time to reflect whether DocBook should serve as the sole official documentation language. Well, I would like to open this to an optional second language.
I don't mind what the second language could be; possible candidates are reStructuredText / Sphinx, Markdown, AsciiDoc -- among others. I don't want to convert DocBook to any other format. But giving projects some choice, might help.
I am by far not the only person with regard to a replacement of DocBook: DigiKam recently switched to Sphinx for their user documentation after 20 years of using DocBook. Krita uses Sphinx for five years and Kdenlive for over a year. By the way, the Linux kernel left DocBook for Sphinx, too.
What do you think? This would be a good topic for an Akademy BoF. Where should we discuss this in the meantime?
Hi,
ReplyDeleteKDE doc infra maintainer here. This is definitely not the first time that the issue was discussed or raised, but it needs work.
Please check my old presentation from Akademy 2017, for example: https://conf.kde.org/en/akademy2017/public/events/377.html
At the time the candidate in my mind was Asciidoc (because it was closer to DocBook and may have made the transition easier) but ReST has since positioned itself as a better choice. Of course it's not just a matter of "let's use it" - the 3 doc websites are a good example, but before we scale that more we may need some more common tooling to centralize the access and avoid scattering the content around.
Thanks Luigi for mentioning the talk from Akademy 2017. It is still worth watching and the questions raised needs to be answered.
ReplyDeleteDepending on the general interest, we need to figure get several things done. Some point, more will come up:
- Decide on the actual tool
- Get proper CMake support, either upstream or in the cmak-extra-module
- Think about ways to integrate the tool in the current toolset, both for developers and KDE servers
- Have a proof of concept project to get feedback first hand.
As most people don't like documentation in general making things as easy should be a priority. That being said the clear option would be Asciidoc as it is simple yet powerful when needed and super easy and approachable. You can easily convert to docbook if need be and it makes it easy to convert to epub, man page, html or pdf. Thirdly it is human readable and non obtuse you can easily edit read and share the document and not run into xml issuer and validation errors. Also you can reference actual code and get it highlighted easily within the documentation.
ReplyDelete