From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.comp.tex.context/57531 Path: news.gmane.org!not-for-mail From: Michael Saunders Newsgroups: gmane.comp.tex.context Subject: docs (was: Re: Microtype in ConTeXt) Date: Sat, 27 Mar 2010 17:08:24 -0500 Message-ID: <54d7f5601003271508r38321f14n860cc9e41f6da676@mail.gmail.com> Reply-To: mailing list for ConTeXt users NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1269727736 21203 80.91.229.12 (27 Mar 2010 22:08:56 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 27 Mar 2010 22:08:56 +0000 (UTC) To: ntg-context@ntg.nl Original-X-From: ntg-context-bounces@ntg.nl Sat Mar 27 23:08:52 2010 Return-path: Envelope-to: gctc-ntg-context-518@m.gmane.org Original-Received: from balder.ntg.nl ([195.12.62.10]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1NveBV-0001Hq-9x for gctc-ntg-context-518@m.gmane.org; Sat, 27 Mar 2010 23:08:49 +0100 Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id DEEF5C9CF6; Sat, 27 Mar 2010 23:08:48 +0100 (CET) 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 q6EhAcLXmm-9; Sat, 27 Mar 2010 23:08:36 +0100 (CET) Original-Received: from balder.ntg.nl (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id 8FAB8C9C8E; Sat, 27 Mar 2010 23:08:36 +0100 (CET) Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id 83296C9CF6 for ; Sat, 27 Mar 2010 23:08:31 +0100 (CET) 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 NHcbJPM1wVJv for ; Sat, 27 Mar 2010 23:08:26 +0100 (CET) Original-Received: from mail-yx0-f184.google.com (mail-yx0-f184.google.com [209.85.210.184]) by balder.ntg.nl (Postfix) with ESMTP id 14B90C9C8E for ; Sat, 27 Mar 2010 23:08:25 +0100 (CET) Original-Received: by yxe14 with SMTP id 14so5032382yxe.5 for ; Sat, 27 Mar 2010 15:08:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:date:received:message-id :subject:from:to:content-type; bh=vtLrzCFtwhuSpbXMhE1Xyp/p7zexSfwftmjZh9iw8Ts=; b=fxQ4lk+sngw71spDgtdoyF1DflTF4PC0ttx9X0tDndSWnE80vzH9RqhVPZF3/13ePD 8kInaQvVBONUJ4lnDR+3ordkn1wOvZd7u4dMF23tg21BULCPIbgJw25REbzlxORUzcKm mjnuqNZhT+LJNGwZP1HoVXzK1mUp8OFf9MOyI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:content-type; b=r4yYOIAmtyZv0r/Sf5x9c7iyYMLnhXSwB+Rvok1+jF/KeSyMHumMxAvzWCVnB1Bn47 3EFefID339y1mq2AZd1ep3ZpeVwx5PTyZmTSu/4Vsu5LuB180d5WhMewQh/ULE1EGXWT u8IrDaoAUfcIq1rxoszocRWRP6qRLPuKd+RfI= Original-Received: by 10.100.10.11 with HTTP; Sat, 27 Mar 2010 15:08:24 -0700 (PDT) Original-Received: by 10.101.2.17 with SMTP id e17mr1424634ani.232.1269727704289; Sat, 27 Mar 2010 15:08:24 -0700 (PDT) X-BeenThere: ntg-context@ntg.nl X-Mailman-Version: 2.1.12 Precedence: list List-Id: mailing list for ConTeXt users List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: ntg-context-bounces@ntg.nl Errors-To: ntg-context-bounces@ntg.nl Xref: news.gmane.org gmane.comp.tex.context:57531 Archived-At: Peter, that post of Hans's mainly argues that the old manual is good enough and then goes on to talk about development. For example: "Even an old manual can quite well describe functionality as much didn't change." It can if it ever did. I don't think cont-eni.pdf etc., describe the functionality well at all. "As one can visually get all kind of output and as typographical elements can interfere the ultimate manual would show $n!$ variants and become quite unreadable. There is no easy way out of this. " There is: describe each option concisely and abstractly, then you need only be concerned with $n$ elements. Almost every LaTeX package manages to do this successfully, and they are very usable. "More documentation would not help all users. " There needn't be more. It needn't be lengthy, just clear, complete, and concise. "There are quite some options that were never meant for usage beyond our own, but as we ship the full product, they become visible. No, they are not documented apart from the source. Yes, if useful they should be documented but why by me? " Because you are probably the only person on earth who understands them. Getting that knowledge out of your head and into others' will require an act of communication. "I only work on a manual (or article or whatever) if it's fun to do." That may be the problem! Hans, Here are some constructive suggestions. I hope you take them seriously: If you ever write another manual, perhaps when MKIV is complete, 1. Start from scratch. Throw away the old material. 2. Forbid yourself the use of code examples. They are a crutch which impedes communication. First, write the whole manual with normal, abstract, expository prose. When it's complete and explains everything fully---when it {\em makes sense}--- {\em then} illustrate it with as many code samples as you like. 3. Have a standard format, a sort of checklist, for what must be said about each argument, parameter, command and group of commands: ---What is its function? ---How is it used? ---What is it used for (what effect is it supposed to achieve)? ---What are the options? A regular format like this will make it much easier on you. You'll have a regular structure that you simply have to fill in. It might even make the task more fun. 4. Get someone to serve as an editor. These will solve most of your writing problems. I look forward to a new manual someday. Thanks, -- Michael ___________________________________________________________________________________ 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 ___________________________________________________________________________________