Re: [NTG-context] State of documentation of ConTeXt?

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 mailto:luigi.scarso@gmail.com>:

On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda mailto:gerben.wierda@rna.nl> wrote:

On 14 Jul 2014, at 19:29, Hans Hagen mailto:pragma@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 -----------------------------------------------------------------