Hi Liam, Thank you for this addition information (and the english lesson, not my mother tongue, I sometimes make mistakes) :) Le vendredi 11 janvier 2019 à 01:09:27, Liam Proven a écrit :
On 11/01/2019 12:43, Sébastien 'sogal' Poher wrote:
I guess that some of you already use one of those. Do you have any advises about which one should I choose, any pros and cons of each ?
Partly it depends on which, if any, projects you would like to align with, and what tooling you want to use.
My project will be independent from any existing base. I would like to document an IT platform for a client, consisting of several services.
Internally, SUSE works almost entirely in GeekoDoc, a flavour of DocBook XML. It's very rich and sophisticated, we have a great FOSS toolchain for it, and it lets you do almost anything you could want.
But it's hard to learn and hard to read. Personally I use a very rich but sadly proprietary Java editor called <oXygen/> for it, mainly for its "author mode" preview.
Geany handles it quite well.
Seems nice but a bit overkill and, as you mentionned, it will took some time to learn. I do not exclude the possibility that this documentation will be updated by my colleagues so the learning curve should not be too steep.
Some teams and projects use AsciiDoctor. This is the modern descendant of AsciiDoc. (The difference is the rendering tools -- AsciiDoc was written in Python, I think, and is no longer maintained. Its successor is the Ruby-based AsciiDoctor.
Personally, I quite like it, and use it for drafting.
It seems pretty easy to learn and use, quite close from Markdown.
RST is used by the kernel and Python teams for their docs. I have not really looked at it.
Markdown is OK but too limited & suffers badly from insufficient standardisation, so there are multiple competing flavours. It also irritates me that it gratuitously diverged from the traditional *email* and *Usenet* _markup_ /conventions/ that Thunderbird and so on support.
P.S. "Advice" is an uncountable noun. Like "information" it has no plural. :-)
-- Liam Proven - Technical Writer, SUSE Linux s.r.o. Corso II, Křižíkova 148/34, 186-00 Praha 8 - Karlín, Czechia Email: lproven@suse.com - Office telephone: +420 284 241 084
-- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
-- Sébastien Poher -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org