Re: How can we decrease the cognitive overhead for contributors?

[Giovanni Biscuolo]

Hi,

Josselin Poiret <dev@jpoiret.xyz> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Texinfo is mostly just plain text until you learn about a few decorators
>> :-).  It gives us the info manuals that I find very nifty (it's like a
>> man page, but with hyperlinks and advanced navigation capabilities!) and
>> used across many GNU projects (e.g. coreutils, Emacs, Bash, GCC, GNU
>> Make, etc.)  I see it as a strength more than a weakness for the
>> project.
>
> I agree with Maxim here, I think the texinfo markup is important to be
> able to generate such a nice manual

my 2 cents...

I've studied and used (some less than others) many available
"lightweight markup language" for documentation purposes: LaTeX,
markdown (manu flavours), restructured-text, AsciiDoc, org-mode, Texinfo

in my experience markdown - thus every wiki periodically is the alleged
missing tool - is _not_ suited at all for documentation, it lacks so
many _semantics_ needed for documentation purposes.

given that markdown (and a wiki) is not suitable for the task of
"writing good documentation", more or less all other markup languages
are of good quality, including Texinfo

additionally, Texinfo can be browsed directly - I mean without being
transformed in the final output format - by several programs [1], some
of them packaged in Guix: emacs, info-reader, pinfo, khelpcenter (GUI),
yelp (GUI); quite good choiche of Texinfo readers.

after all, Texinfo is a wise choiche IMO.

[...]

Happy hacking, Gio'



P.S.: not that Texinfo is the best /document programming framework/
(yes: the book is a program), the best ones are skribilo (Guile) and
Pollen (https://docs.racket-lang.org/pollen/)... and org-mode publish
:-)


[1] https://en.wikipedia.org/wiki/Info_(Unix)#List_of_Info_readers

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

signature.asc
Description: PGP signature