[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [lojban] Documentation standards.
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.