On 7/15/2014 5:33 PM, Yuri Teixeira wrote:
As I wrote in another thread, the state of the docs worries me too. I
take it that the suggestion to study the source was not serious, and
perhaps it is indeed a matter of priorities. As a new user I have a
strong opinion that the documentation should be a higher priority than
it seems to be. All the arguments about how many person-hours it would
take and the huge task it is, in my eyes, only furthers the point that
it is not considered as important as doing "real development". I
Well, without development (like luatex and mp and fonts and so) it would
be a dead end anyway. Also, without some of the new things I could not
use context myself in projects (and thereby put time in it).
consider the docs a core part of the project, and the code another part,
hence the disagreement in regards to the priorities. Pro-bono or not is
not an issue, since time is spent on the project in some form. Writing
features that few people know about and are able to use is only half of
the dev work.
Most mechanism that are new or renewed also come with pretty recent
manuals (like xtables and new bibliography support); older code is
mostly compatible with what old manuals describe (ok we could just bump
the date to 2014 but why). For me that's the most I can so ... write in
sync with development. (I simply run out of time otherwise.)
But I get it that documenting is a pain, and seemingly frivolous work.
The separate manuals may have been good, but they look fragmented and
there is no unified docs to go to when in doubt. And having one place to
go is even easier to maintain than many. The wiki is a nice idea, but it
needs much more rigour to function as real docs.
hm, I spend quite some time on writing code but also on documentations;
did you read the xtable, xml, cld, fonts, metafun, etc manuals as well
as mk, hybrid, allkind? It's up to others to translate that into
something better. There are articles published (ok, in that case it
helps to be a member if a user group, which helps keeping tex alive
anyway).
There are also examples in the test suite that can probably be turned
into docu.
Some suggestions. I'm assuming some form of wiki-like website that can
be the contextgarden or (preferably) another official
docs/wiki/wiki-like site.
everyone can write documentation (and it also happens) ... we have the
wiki etc to publish them .. and everyone can conrtibute to make the wiki
better (and provide pointers to documentation)
All the content of the manuals should be unified in this site.
If a crowdsourcing/users-can-do-it approach is taken, a clear structure
needs to be previously laid out, so that we know what blanks to fill.
And even with collaboration/feedback, core people should do it.
It is important that reviewing and check marking the new edits be done
by some authoritative group, so that the community knows what to trust,
what should work as documented so that we can report real issues.
It is important to label the information as reviwed and up to date, and
to which version it applies, mkii/mkiv
If this structure is put on top of the context garden, some labeling is
needed to distinguish the extra pages from the structural docs pages.
the problem there is that it needs some users who dedicate time and so
that for many years in order to keep consistency (btw, there are some
real good sections on the wiki already)
There are many good examples out there of good docs structure and
presentation. I'm willing to collaborate what I can with my limited
knowledge and time, even if little while writing my master's thesis.
In that case, coordinate with Sietse. One of the things we want to (be)
do(ne) is a split between mkii and mkiv on the wiki.
Sorry to annoy with this again,
No problem, as you also offer to help,
YT
2014-07-15 11:55 GMT-03:00 luigi scarso <luigi.sca...@gmail.com
<mailto:luigi.sca...@gmail.com>>:
On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda
<gerben.wie...@rna.nl <mailto:gerben.wie...@rna.nl>> wrote:
On 14 Jul 2014, at 19:29, Hans Hagen <pra...@wxs.nl
<mailto:pra...@wxs.nl>> wrote:
quite some sub-systems are described in their own manuals
(fonts, tables, xml, ...) and these manuals are quite up to
date (and easier to maintain than one big fat manual
also, additional documentation is something that users need to
participate in (just pick a topic)
even if it has high priority, that doesn't mean that those
involved have much free time left to do that next to their
regular work (as usual most development is done in spare time)
so, patience is needed,
I like ConTeXt (still do, I liked its approach when I first
encountered it). But the project is more the ongoing private
tinkering of a small in-crowd (that communicates with some
followers).
ConTeXt is managed a bit like a small group of researchers
sharing a couple of complex and undocumented models/programs and
tinkering with them as they go along. It’s an activity without
formal design, but with a lot of trial-and-error/testing.
Given that status (and the fact that it has had that status for
over a /decennium/), I don’t expect it to ever become a serious
product that is (semi-)professionally managed. I prefer content
over management every day, but something like this needs some
minimal management. That requires both time (=money) and
capabilities. Besides, the tinkering researchers may not be
inclined to do that, they want to tinker.
BTW, you can’t be serious asking the /users/ to provide the
documentation, can you?
These are still good
Fonts in ConTeXt
Layouts in ConTeXt
MetaFun manual
MKII - MKIV, the history of LuaTeX
http://www.h2o-books.com/catalog/5
--
luigi
___________________________________________________________________________________
If your question is of interest to others as well, please add an
entry to the Wiki!
maillist : ntg-context@ntg.nl <mailto:ntg-context@ntg.nl> /
http://www.ntg.nl/mailman/listinfo/ntg-context
webpage : http://www.pragma-ade.nl / http://tex.aanhet.net
archive : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___________________________________________________________________________________
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the
Wiki!
maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage : http://www.pragma-ade.nl / http://tex.aanhet.net
archive : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___________________________________________________________________________________
--
-----------------------------------------------------------------
Hans Hagen | PRAGMA ADE
Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com
| www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the
Wiki!
maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage : http://www.pragma-ade.nl / http://tex.aanhet.net
archive : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___________________________________________________________________________________
