Hello everyone!
As an eternal newbie (with a memory like a goldfish), I started by
building my own documentation from the web pages constructed by Bertrand
Masson (prehistory archaeologist in Northern France) "les fiches à
Bébert" (obsolete version here: http://bertrandmasson.free.fr/; new
recommended version here:
http://lesfichesabebert.fr/TeX/context/context-intro.html). As
mentionned by Alain Delmotte.
Bertrand Masson always keeps his site up to date, as he gives references
to the documentation compiled by Garulfo (Joaquín Ataz López ),
available in several languages, which I personally found well-done,
useful and welcome. It's interesting to note with a rather positive
smile that documentations, even if they're never really up to date in
the details of ConTeXt's evolution, copy each other: that's what I did
to write the beginning of a Wikibook in French
(https://fr.wikibooks.org/wiki/ConTeXt/Qu%27est-ce_que_ConTeXt_%3F). I
took things written by Bertrand Masson and was partially taken over by
Garulfo and so on.
Fortunately, the ConTeXT discussion list offers MWEs: all you have to do
is to test them and save these examples on your system in the CTX-TESTS
document folder. The next step is to classify these examples under the
appropriate headings, then insert them into a coding system for a
complex document that always calls for requests for explanations from
discussion list participants.
This question of documentation seems to me to be an age-old snake, not
only on a technical subject which can be complex, as ConTeXt can be, but
also concerning other types of documentation. For my part, although I
haven't yet exhausted all the available documentation resources, whether
internal to the distribution, or online like the ConTeXt Garden wiki, I
think (but this has been better expressed here by others than me) that a
real documentation refresh could be carried out collectively, with the
great ambition of keeping obsolete documentation in an archive, while
proposing a wiki with the date of update visible, in correlation with
the PDF version. I have no idea how this documentation update could be
achieved, but the fact is that it would be desirable to devote a section
to the purely technical and basic aspects of CTX installation and font
availability on Windows, Mac OS, Linux, BSD, etc., with MWEs and
examples a little more detailed. Once this documentation has been passed
as an introductory part (itself containing chapters explaining how this
page of documentation was put together, with notes in the margins,
etc.), this book could introduce MKIV, LuaTeX, MetaPost and so on, but
with a clear distinction between the objectives sought: writing
documentation with figures, writing a thesis in mathematics and physics,
how to construct figures, or a bibliography. Not to mention the handling
of photographs in an aesthetically demanding layout; all this with the
possibility of showing complete or partial examples of work produced...
In a nutshell: even if I give the impression that I'm asking you to
reinvent the wheel, in reality it's a question of collating relevant
existing information in a way that is intelligible and clear to the
neophyte, but that also meets the demands of experienced users, who
don't all use ConTeXt for the same reasons. Don't get me wrong: I'm not
telling you what to do, I'm just giving you my opinion. Basically, I'm
saying: documentation exists, but it has to be reliable, up to date,
easy to find and enable you to make progress in difficult situations. As
I said, I found Garulfo's work very welcome. It's not obsolete and
doesn't need replacing. But perhaps it could be amended on certain
points and completed and made available both in PDF and online in the
ConTeXt Garden wiki pages?
So, if by hypothesis the relevant documentation exists, here and there,
but it's in the middle of pages that are in the past, it can be
considered a daunting task to go looking for information that you
realize is no longer up to date, because experience shows that it's no
longer reliable. If confusion reigns, those seeking to apply what
they've read risk turning away from ConTeXt, or asking the same
questions over and over again.
So there's plenty of food for thought to be had when it comes to methods
for overhauling existing documentation. It's not a question of thinking
long and hard about the availability of this documentation (on line or
as a PDF?), but rather of knowing whether to build an encyclopedia, or a
series of manuals, each of which is intended to circumscribe as closely
as possible the problems encountered when attempting this or that form
of page layout.
I remember being astonished to discover, when I first started learning
ConTeXt, all the vocabulary that existed around page layout (in French:
Grand fond, petit fond, blanc de tête, blanc de pied, etc.), vocabulary
that we ignore when we come from Word office automation (see
