From lojban+bncCInbwevEGxDzpITeBBoENzl9XQ@googlegroups.com Sat Apr 10 17:06:34 2010 Received: from mail-pv0-f189.google.com ([74.125.83.189]) by chain.digitalkingdom.org with esmtp (Exim 4.71) (envelope-from ) id 1O0kh3-00069s-Qq; Sat, 10 Apr 2010 17:06:34 -0700 Received: by pvb32 with SMTP id 32sf1239640pvb.16 for ; Sat, 10 Apr 2010 17:06:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=beta; h=domainkey-signature:received:x-beenthere:received:received:received :received:received-spf:received:x-mathnet-spam-score :x-rcvd-authsender:date:from:to:subject:in-reply-to:message-id :references:user-agent:mime-version :x-original-authentication-results:x-original-sender:reply-to :precedence:mailing-list:list-id:list-post:list-help:list-archive :x-thread-url:x-message-url:sender:list-subscribe:list-unsubscribe :content-type; bh=JjTIDDJnOXhD3hLJ//kKtgT3c5JQRma+QInVuHH8XGo=; b=imkG5+HF++195ih3awS6yQVFkeMseDEdM/G4kp8cOzG2izdIPS5dgLTWPIPBx9e1xW /hOeJ5O0/c5Hnw8fZN2HUrnY1VTOlaucjLGjDdgl89eUp+qHerKtBzW3GEAwPqxa198I PoDyiRZhV2uxAERpTc9mZ3CNTYNVzyNIoQzEw= DomainKey-Signature: a=rsa-sha1; c=nofws; d=googlegroups.com; s=beta; h=x-beenthere:received-spf:x-mathnet-spam-score:x-rcvd-authsender :date:from:to:subject:in-reply-to:message-id:references:user-agent :mime-version:x-original-authentication-results:x-original-sender :reply-to:precedence:mailing-list:list-id:list-post:list-help :list-archive:x-thread-url:x-message-url:sender:list-subscribe :list-unsubscribe:content-type; b=yltwcnIxenyIBNxJJkRR3PAFJUyMzPwNYERnLxdpjcq2uLE8P17qkqBZY2VqXP0igr 5oeDYcoCejZ/s0B0wulIXpeumSGE2kTHcPuPN6WtXSaqrGOtR3imLSYEBugczxowNLwx 1OVAvE9R0PZwrYFlyZt+qk1jO1cbWkvLr6yjg= Received: by 10.115.101.15 with SMTP id d15mr132903wam.10.1270944371533; Sat, 10 Apr 2010 17:06:11 -0700 (PDT) X-BeenThere: lojban@googlegroups.com Received: by 10.114.250.4 with SMTP id x4ls559168wah.3.p; Sat, 10 Apr 2010 17:06:05 -0700 (PDT) Received: by 10.115.98.7 with SMTP id a7mr364304wam.29.1270944363136; Sat, 10 Apr 2010 17:06:03 -0700 (PDT) Received: by 10.115.98.7 with SMTP id a7mr364303wam.29.1270944363119; Sat, 10 Apr 2010 17:06:03 -0700 (PDT) Received: from sumac.math.ucla.edu (sumac.math.ucla.edu [128.97.4.21]) by gmr-mx.google.com with ESMTP id 24si568623pzk.1.2010.04.10.17.06.03; Sat, 10 Apr 2010 17:06:03 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of jimc@math.ucla.edu designates 128.97.4.21 as permitted sender) client-ip=128.97.4.21; Received: by sumac.math.ucla.edu (Postfix, from userid 1886) id B9B1441CC9; Sat, 10 Apr 2010 17:06:02 -0700 (PDT) X-Mathnet-Spam-Score: 1.5/5.0 X-Rcvd-AuthSender: from xena.cft.ca.us (pool-71-119-248-235.lsanca.dsl-w.verizon.net [71.119.248.235]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) (Authenticated sender: jimc@math.ucla.edu) by sumac.math.ucla.edu (Postfix) with ESMTPSA id 457C141CC7 for ; Sat, 10 Apr 2010 17:06:01 -0700 (PDT) Date: Sat, 10 Apr 2010 17:06:01 -0700 (PDT) From: Jim Carter To: lojban@googlegroups.com Subject: Re: [lojban] Documentation standards. In-Reply-To: <20100410072623.GA31246@digitalkingdom.org> Message-ID: References: <20100410072623.GA31246@digitalkingdom.org> User-Agent: Alpine 2.00 (LNX 1167 2008-08-23) MIME-Version: 1.0 X-Original-Authentication-Results: gmr-mx.google.com; spf=pass (google.com: best guess record for domain of jimc@math.ucla.edu designates 128.97.4.21 as permitted sender) smtp.mail=jimc@math.ucla.edu X-Original-Sender: jimc@math.ucla.edu Reply-To: lojban@googlegroups.com Precedence: list Mailing-list: list lojban@googlegroups.com; contact lojban+owners@googlegroups.com List-ID: List-Post: , List-Help: , List-Archive: X-Thread-Url: http://groups.google.com/group/lojban/t/c970d9f553a54fe6 X-Message-Url: http://groups.google.com/group/lojban/msg/393926820ea0cb96 Sender: lojban@googlegroups.com List-Subscribe: , List-Unsubscribe: , Content-Type: TEXT/PLAIN; format=flowed; charset=ISO-8859-1 On Sat, 10 Apr 2010, Robin Lee Powell wrote: > Side effect of the bigger discussions; had to get this off my chest. > > http://teddyb.org/robin/tiki-index.php?page=Documentation+Standards+For+Lojban I think this plan is a very good idea. I do have a few nitpicks, though: To me, "documentation standards" means things like "Subsection titles shall use our subsection tag (H3 in HTML) and not idiosyncratic author-crafted formatting, so our CSS will apply and give a uniform appearance. After the title a Lojban example shall appear, under the secexample class tag (which blockquotes and italicizes), illustrating the issue covered in the subsection...." In other words, low-level formatting and mid-level content specs. Putting forth a wishlist of what to document, and at what levels, is good to do (particularly if eventually accomplished) but I don't see it as the referent of the name given. Being lazy, I feel annoyed when documents (particularly print media) over-use cross-references; the work of digging up the numerous link targets may exceed the value I get from having my question answered. Hyperlinks are much nicer in this regard. But judicious repetition can really enhance the document. Injudicious repetition, though, makes it a flaccid mess. The current foo-rah is straining my mailbox but I think it's very valuable for the future of Lojban and I thank you [rlp] for articulating the issues coherently and bringing up quite a number of valuable points, including this one about documentation. James F. Carter Voice 310 825 2897 FAX 310 206 6673 UCLA-Mathnet; 6115 MSA; 405 Hilgard Ave.; Los Angeles, CA, USA 90095-1555 Email: jimc@math.ucla.edu http://www.math.ucla.edu/~jimc (q.v. for PGP key) -- You received this message because you are subscribed to the Google Groups "lojban" group. To post to this group, send email to lojban@googlegroups.com. To unsubscribe from this group, send email to lojban+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/lojban?hl=en.