Larry Wall larry-at-wall.org |Perl 6| wrote:
Just so you don't think this is warnocked, I'm looking at it, and
thinking about it.
Thanks. I thought perhaps everyone filtered it out since it had a bad
subject line.
By and large it seems to be going the right
direction, though I've naturally got a number of quibbles.
Probably each quibble needs to be a separate thread though, since
many of them will probably breed discussion.
On a larger question, I'm wondering if it's time to slush/freeze
the Synopses as historical documents and put all spec effort into
the new form (presumably as a wiki that knows how to serialize into
a document). I don't think we have the bandwidth to maintain multiple
standard documents. Well, okay, *I* don't have the bandwidth...
You might need to teach some of us how to write in Standardese,
however. :)
If we did set up a wiki, we could have some of the specific language
lawyering discussions attached to the specchunk in question, which
seems like a good idea to save wear and tear on our email clients,
and to prevent recurring FAQs.
We'll probably need to exercise a modicum of control over who gets
to revise the spec. We also probably need to have a discussion of
whether the current section outline is optimal, and if not, whether
it needs fixing now or can be simply renegotiated via wiki.
Larry
I was contemplating that a Wiki or other hypertext format might
alleviate the issue of "outlining" since it would not have to have a
unique outline, but can refer to definitions and other concepts as it
goes, and have multiple organizing pages of links.
I'm having no problem re-arranging the outline as things suggest
themselves, just by dragging. I agree that a hyperdocument would render
that moot.
Right now, since I have a "productive period" of full-time effort, I'd
like to keep pouring stuff in myself. And work on standard language and
terminology by posting threads like the current one on BEGIN etc.
I'm really pulling on three straws at the same time:
1) copy every fact from the Synopses documents to the new outline.
2) flesh out things that are not explained well, have conflicts, etc.
3) state things in formal language.
The synopses combine tutorial and specification. The spec doc should be
specification, without "explanation" to a certain extent. For the
casual reader, this renders it unfathomable. So I think explanation and
discussion of a feature can be linked in as non-normative sections.
As a hyperdocument, there are several kinds of pages (or content on one
physical page):
- the formal spec itself
- explanation to give an approximate understanding of what the spec
will say
- rationale on why things were done a certain way
- commentary and feedback of any other content
- implementation notes for specific implementations
These can be clearly differentiated by style, so explanation and formal
spec could be mixed on a page much as "literate programming" mixes code
and comments.
Maybe we need to start identifying a documentation system that does what
we need.
I think I can teach "standardeze" by example once I get some worked in
there. I never really thought about it; it just grows on you. It's
more like programming than essaying, is how it feels. Vocabulary is
important: use the correct term for the concept, watch your "will",
"shall", etc. as that is the "programming" of the actual specification.
--John
