Some conversations on the main mailing list led to me thinking about what I would like the documentation for Lojban to look like if I were king of the universe. Some of this is, I think, non-obvious, so here it is.

"What Is Lojban?" is largely outside of what I'm talking about here. I'm talking about explicit learning materials for the language ("Lojban For Beginners" and similar), dictionaries and the like, and full-on semantic and grammatical references (the CLL).

What I'd like to see is this:

• A set of hierarchical documents with limited overlap. I see the advantages of having something that is a one-stop reference like the CLL, but such a reference should be very limited in the amount of teaching it attempts to do, instead being a reference only.
  • By hierarchical I mean that the lowest-level document should be as simple as possible, and each document should build on the previous one, with an emphasis on referring to each other, rather than repeating material.
  • This means that the reference document's section on something might begin with "See L4B chapters 7 and 12, and L4I(ntermediates) chapter 8", or whatever.
• Each document should encompass a complete level of understanding of the language.
  • By this I mean that, for example, the document for beginners should give the reader enough understanding of the language to be able to visit Lojbanistan and get around the city and order dinner and suchlike, and should only explain the grammar to the minimum level required for that task. By contrast, the next level up might get into sei clauses or using NU outside of a sumti, or similar things that are routinely useful but not in every conversation, and the next level after that (probably the reference itself) might discuss rare things like termsets.
• The various documents should use a consistent vocabulary to talk about Lojban's parts of speech, and those terms should be in Lojban. I would be very happy to never see the word "modal" used in Lojban discussion again, and even words like "attitudinal" are dangerous because they make English speakers think they know what's going on, even though the behaviour of the words themselves is purely Lojbanic.
  • This vocabulary should be used for cross-referencing; "for more on sumtcita, see CLL chapter 4 section 8" (or whatever)
  • This is particularily helpful with the dictionary: a word can simply say "is a sumtcita", or whatever, and save a lot of verbiage by expecting people to refer to the other documents for what that means (a foreward would have to explain that, of course)
• I think that every question about the language that comes up should be answered somewhere. It is therefore probably appropriate that some of the formal documentation, in the form of answers to such questions, be online-only and easily searchable. There are going to be situations where the interaction of various rules is going to require even the most hardened experts to really sit down and think, and the results of such deliberations should be recorded, but it is certainly not appropriate to include a big list of answers to things like "what does {mi nu klama ke gerku co cevni du'u pritu} mean?" in any of the printed documents (although people are certainly welcome to print it out themselves if they've a mind to).
• The various documents should have fantastic indexes.
  • All the indexes should be collected together in a master index which can be printed out. This is another place where having consistent vocabulary is really important.
• All documentation should be in a format that allows for easy book printing and well laid out, hyperlinked online versions, from the same source. Various people got together and settled on DocBook for this purpose.
  • As part of this, they should be easily searchable online.