Re: State of documentation of ConTeXt?

[Yuri Teixeira <yuriteixeira235@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4787 bytes --]

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 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.

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.

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.
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.

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.

Sorry to annoy with this again,

YT



2014-07-15 11:55 GMT-03:00 luigi scarso <luigi.scarso@gmail.com>:

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

[-- Attachment #1.2: Type: text/html, Size: 9380 bytes --]

[-- Attachment #2: Type: text/plain, Size: 485 bytes --]

___________________________________________________________________________________
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
___________________________________________________________________________________