From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.comp.tex.context/88107 Path: news.gmane.org!not-for-mail From: Yuri Teixeira Newsgroups: gmane.comp.tex.context Subject: Re: State of documentation of ConTeXt? Date: Tue, 15 Jul 2014 12:33:39 -0300 Message-ID: References: <1642f57885676cbd1020027a2bff7c40.squirrel@webmail.xs4all.nl> <53C41372.7080802@wxs.nl> Reply-To: mailing list for ConTeXt users NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1885610929==" X-Trace: ger.gmane.org 1405438462 29750 80.91.229.3 (15 Jul 2014 15:34:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 15 Jul 2014 15:34:22 +0000 (UTC) To: mailing list for ConTeXt users Original-X-From: ntg-context-bounces@ntg.nl Tue Jul 15 17:34:18 2014 Return-path: Envelope-to: gctc-ntg-context-518@m.gmane.org Original-Received: from balder.ntg.nl ([5.39.185.229]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1X74kA-00026h-M8 for gctc-ntg-context-518@m.gmane.org; Tue, 15 Jul 2014 17:34:14 +0200 Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id D86DF102B4 for ; Tue, 15 Jul 2014 17:34:13 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at balder.ntg.nl Original-Received: from balder.ntg.nl ([127.0.0.1]) by localhost (balder.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id yUjBmCjcELef for ; Tue, 15 Jul 2014 17:34:13 +0200 (CEST) Original-Received: from balder.ntg.nl (localhost [IPv6:::1]) by balder.ntg.nl (Postfix) with ESMTP id 6C10310222 for ; Tue, 15 Jul 2014 17:34:05 +0200 (CEST) Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id 812C4101E3 for ; Tue, 15 Jul 2014 17:34:01 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at balder.ntg.nl Original-Received: from balder.ntg.nl ([127.0.0.1]) by localhost (balder.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id Q+0hDT3jOerx for ; Tue, 15 Jul 2014 17:33:56 +0200 (CEST) Original-Received: from filter4-ams.mf.surf.net (filter4-ams.mf.surf.net [192.87.102.72]) by balder.ntg.nl (Postfix) with ESMTP id 08731101E2 for ; Tue, 15 Jul 2014 17:33:56 +0200 (CEST) Original-Received: from mail-qc0-x233.google.com (mail-qc0-x233.google.com [IPv6:2607:f8b0:400d:c01::233]) by filter4-ams.mf.surf.net (8.14.3/8.14.3/Debian-9.4) with ESMTP id s6FG09fn002151 (version=TLSv1/SSLv3 cipher=RC4-SHA bits=128 verify=NOT) for ; Tue, 15 Jul 2014 18:00:24 +0200 Original-Received: by mail-qc0-f179.google.com with SMTP id r5so4321480qcx.38 for ; Tue, 15 Jul 2014 08:33:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=SeRRUVD+jwkA4PjSLQhq1PoDZBWUvICw9h43J6BYKcQ=; b=W1W7rAtBHKeYWE8WNtxrrhfBQ/SZ5EkmC2YcSku0A71T6OX8QXER9bhN6H98/yW1vu qVuXuf1+3kWjeKYgze5NMt0xVkzGEVU8mdJt0kmsfB9QjIK/m1eYLc6Mi7gvJCkTE5+Q cWRUpzmDUhE3FE9oSwiNsc9lAxR2UD39M8SHIzCJZ6LCEKJ8mmbT72AfxWPmtjoWlmkc qI/RuqJ+wJbyptfMYjg7PpvOy+vZZurg5nzuPJZaF74ZVXyTbTgemM9W1uSGZ9rsXBmu 5Kngna8QpbRKdKQbbqq4tdyglPdCDqDUITVVWbxDMTvEtTc/WL50hgiN2JrhM65did/J RxWA== X-Received: by 10.224.129.201 with SMTP id p9mr34300632qas.45.1405438419271; Tue, 15 Jul 2014 08:33:39 -0700 (PDT) Original-Received: by 10.140.20.131 with HTTP; Tue, 15 Jul 2014 08:33:39 -0700 (PDT) In-Reply-To: X-Bayes-Prob: 0.0001 (Score 0, tokens from: ntg-context@ntg.nl, base:default, @@RPTN) X-CanIt-Geo: ip=2607:f8b0:400d:c01::233; country=US X-CanItPRO-Stream: uu:ntg-context@ntg.nl (inherits from uu:default, base:default) X-Canit-Stats-ID: 01MqE0aK0 - f8590d6bd52b - 20140715 (trained as not-spam) X-Scanned-By: CanIt (www . roaringpenguin . com) X-BeenThere: ntg-context@ntg.nl X-Mailman-Version: 2.1.14 Precedence: list List-Id: mailing list for ConTeXt users List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ntg-context-bounces@ntg.nl Original-Sender: ntg-context-bounces@ntg.nl Xref: news.gmane.org gmane.comp.tex.context:88107 Archived-At: --===============1885610929== Content-Type: multipart/alternative; boundary=001a11c2cc0abc07d304fe3d2106 --001a11c2cc0abc07d304fe3d2106 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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 : > > > > On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda > wrote: > >> On 14 Jul 2014, at 19:29, Hans Hagen 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 th= em >> as they go along. It=E2=80=99s an activity without formal design, but wi= th 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=E2=80=99t expect it to ever become a serious product= that is >> (semi-)professionally managed. I prefer content over management every da= y, >> but something like this needs some minimal management. That requires bot= h >> time (=3Dmoney) and capabilities. Besides, the tinkering researchers may= not >> be inclined to do that, they want to tinker. >> >> BTW, you can=E2=80=99t 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 > > _________________________________________________________________________= __________ > --001a11c2cc0abc07d304fe3d2106 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
As I wrote in another t= hread, the state of the docs worries me too. I=20 take it that the suggestion to study the source was not serious, and=20 perhaps it is indeed a matter of priorities. As a new user I have a strong= =20 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=20 the huge task it is, in my eyes, only furthers the point that it is not=20 considered as important as doing "real development". I consider t= he docs a core part of the project, and the code another part, hence the disagreem= ent in regards to the=20 priorities. Pro-bono or not is not an issue, since time is spent on the pro= ject 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 docume= nting is a pain, and seemingly frivolous work. The separate manuals may hav= e 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/w= iki-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 structu= re needs to be previously laid out, so that we know what blanks to fill. An= d even with collaboration/feedback, core people should do it.
It is important that reviewing and check marking the new edits be don= e by some authoritative group, so that the community knows what to trust, w= hat 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 to= p of the context garden, some labeling is needed to distinguish the extra p= ages 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 kno= wledge 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@gmai= l.com>:



On Tue, Jul 1= 5, 2014 at 11:59 AM, Gerben Wierda <gerben.wierda@rna.nl>= wrote:
On 14 Jul 2014, a= t 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 m= aintain than one big fat manual

also, additional documen= tation is something that users need to participate in (just pick a topic)

even if it has high prio= rity, 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 s= pare time)

so, patience is needed,<= /span>

I like ConTeXt (still do, I liked its app= roach when I first encountered it). But the project is more the ongoing pri= vate tinkering of a small in-crowd (that communicates with some followers).=

ConTeXt is managed a bit like a small group of research= ers sharing a couple of complex and undocumented models/programs and tinker= ing with them as they go along. It=E2=80=99s an activity without formal des= ign, but with a lot of trial-and-error/testing.

Given that status (and the fact that it has had that st= atus for over a decennium), I don=E2=80=99t 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 manag= ement. That requires both time (=3Dmoney) and capabilities. Besides, the ti= nkering researchers may not be inclined to do that, they want to tinker.

BTW, you can=E2=80=99t be serious asking the users to provide the documentation, can you?


These are still good

Fonts in ConTeXt
Layouts in ConTeXt
MetaFun manual
MKII - MKI= V, the history of LuaTeX

--
luigi

_______________________________________________________________________= ____________
If your question is of interest to others as well, please add an entry to t= he Wiki!

maillist : ntg-context@ntg.nl / <= a href=3D"http://www.ntg.nl/mailman/listinfo/ntg-context" target=3D"_blank"= >http://www.ntg.nl/mailman/listinfo/ntg-context
webpage =C2=A0: http= ://www.pragma-ade.nl / http://tex.aanhet.net
archive =C2=A0: http://foundry.supelec.fr/projects/contextrev/
wiki =C2=A0 =C2=A0 : http://contextgarden.net
___________________________________________________________________________= ________

--001a11c2cc0abc07d304fe3d2106-- --===============1885610929== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ___________________________________________________________________________________ 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 ___________________________________________________________________________________ --===============1885610929==--