Re: State of documentation of ConTeXt?

[Hans Hagen <pragma@wxs.nl>]

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.scarso@gmail.com
> <mailto:luigi.scarso@gmail.com>>:
>
>
>
>
>     On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda
>     <gerben.wierda@rna.nl <mailto:gerben.wierda@rna.nl>> wrote:
>
>         On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl
>         <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
-----------------------------------------------------------------
___________________________________________________________________________________
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
___________________________________________________________________________________