'Function', 'arguments', & 'args' are "wrong" terminology.

[xykj61]

There are a number of docs which, out of seemingly being hastily written from familiarity, use "non-Urbit" technical terminology such as 'functions' and 'arguments' instead of 'gate' and 'sample', just to name a few. Not a huge deal, but as with many of the other things I'm going through, it might help to be consistent.

@cgyarvin, thoughts?

[galenwp]

I honestly feel like we should be doing more of that, and earlier on. Or at least provide some kind of a glossary / key.

[galenwp]

As per: https://github.com/urbit/docs/issues/134

[cgyarvin]

Sorry, I should have answered this. It's a tough problem. I favor consistency but not at the expense of self-parody. I don't know how much that helps you in the trenches.

One very missing thing in Urbit is a good glossary. If our doxology linked routinely to the glossary, it would be much less of a problem.

On Thu, Feb 9, 2017 at 11:55 AM, Galen Wolfe-Pauly <notifications@github.com

wrote:

As per: urbit/urbit.org#850 https://github.com/urbit/docs/issues/134

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/137#issuecomment-278753658, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAR0e1AXZeKPVRNrQl-hb_L_q7jdSks5ra28kgaJpZM4L7rbj .

[galenwp]

Well, there is this: http://urbit.org/docs/about/glossary/. Perhaps we should extend it with a kind of rosetta stone section.

[cgyarvin]

Agreed, I think it'd be a great thing for Keaton to improve.

On Thu, Feb 9, 2017 at 12:02 PM, Galen Wolfe-Pauly <notifications@github.com

wrote:

Well, there is this: http://urbit.org/docs/about/glossary/. Perhaps we should extend it with a kind of rosetta stone section.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/137#issuecomment-278755747, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAZ2WNiMkvUNTxlXluKGIzGlAkr1Yks5ra3C5gaJpZM4L7rbj .

[cxk280]

Pull request urbit/docs#172 starts building on Galen's suggestion.

[ngzax]

Since urbit/docs#172 has been merged, this issue probably should be closed.

[Fang-]

urbit/docs#172 doesn't seem to solve inconsistent use of function vs gate, args vs sample etc. Having glossaries for those kinds of "translations" helps, but doesn't address the core of this issue.

[joshuareagan]

Ideally we'd generally use "sample" and "gate" rather than "argument" and "function", and when we introduce new Urbit terms in a document (or doc series) we'd link to the relevant part of the glossary.

The problem though, is that the glossary mostly uses strict definitions, as it almost certainly should. So when a beginner looks something up, the definition includes two or three more terms he must also look up, and a recursive nightmare begins.

The difficulty when first approaching Hoon/Urbit is that there is a whole network of new, inter-related concepts one must learn; and if one doesn't yet know any of them, it's tough to "break through" and learn any one of them.

There is a tension between strict rigor and approach-ability of the documentation. One way to ease this tension is to make the learning process "linear" rather than "holistic". By this I mean, basically, having a doc series that starts with normie words, slowly introduces new concepts in terms of the normie ones, and at the end you can make use of the glossary without too much pain. To some extent this is what the Urbytes, Hoon docs, and Arvo docs do, but perhaps not always in a systematic or planned way.

Another possible way to resolve the tension is to have two parts for each term in the glossary: (i) the strict definition, (ii) the definition for earthlings, which sacrifices accuracy for pedagogy. (Or maybe we could have two glossaries, one Martian, one earthling.)

[belisarius222]

I think having both strict definition and discussion linkable from the docs is a good idea. Maybe each glossary item should include only the strict definition and a link to the longer definition and discussion.

It should be possible to teach hoon without the recursive nightmare. I think having a "learn you a hoon" guide that goes painfully slowly might be the way to go: first teach basic hoon expressions, such as 42, +, -, and .. Then build up to =(15 15), then ?: =(15 15) %good %bad, and go through detailed examples of all the basic types, including lists and :-. Then teach the basic subject-mutating runes: =>, =/, and =+, lark syntax, and %= and the irregular foo(a new-a, b new-b). Next is probably |-, then maybe |., then |=, then |_ and |^. As this is going along, it should explain the spans and compiled nock that come out of each of these expressions, along with descriptions of how to use !=, !>, and ? in the dojo so you can play with them yourself. Building a recursive gate with variable declarations and casting would show up near the end of this kind of guide, not the beginning. To fully understand that, you actually need to know quite a bit about hoon works. So instead of teaching hoon impressionistically and asking the student to suspend disbelief about the parts where we've waved our hands, we could build up the various abstractions in hoon one-by-one, so that by the time the student needs to understand a recursive gate or complex core, they already know the constituent abstractions and none of the steps are particularly difficult.

I do realize this is easier said than done.

[joshuareagan]

The question important here is this: how much do we bootstrap from non-Urbit concepts as we teach Hoon in the documentation? I'm defending at least a modest degree of such bootstrapping, and it sort of seems like that makes mine a dissenting voice.

Of course the docs you're talking about sound great, Ted, so you should write them. :)

[cgyarvin]

Ted should definitely write them. (Ted doesn't know it, but in the next phase of his employment, we're going to chain him to the wall and feed him only water and crushed Adderall.)

On Mon, Oct 2, 2017 at 7:11 PM, Joshua Reagan notifications@github.com wrote:

The question important here is this: how much do we bootstrap from non-Urbit concepts as we teach Hoon in the documentation? I'm defending at least a modest degree of such bootstrapping, and it sort of seems like that makes mine a dissenting voice.

Of course the docs you're talking about sound great, Ted, so you should write them. :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/137#issuecomment-333718802, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAa4rdpdQa-PgRolDIqvaVwIfo7UKks5soZfLgaJpZM4L7rbj .

[mattlevan]

Perhaps this is a stretch for this issue thread, but hey. My thoughts on this and the docs more generally:

Josh and Ted are right, first off. There's certainly some truth to the recursive nature of learning Urbit with the docs, as a newbie. There also must be room for both extensive and strict definitions as well as longer discussions in the glossary. I think we're missing a huge point and need to zoom out further, though, regarding the state of the docs and their evolution for efficacy. (By the way, when will the docs begin adhering to Kelvin versioning? ;)

Anywho, let me begin by saying: I am a visual learner. To me, I think it'd be really helpful to have a visualized semantic web for Urbit. Of course, something like this is even more difficult than the improvements to the docs and glossary mentioned above, but I think it may be a worthwhile longterm endeavor to pursue.

Introducing Urbit to people is fairly difficult. Thanks to you guys, what's lacking is not fairly refined technical documentation, complete (mostly) with detailed discussions, examples, tutorials, and exercises. What's lacking is the visual communication. For technically-oriented friends, there has been no greater godsend than the yet unpublished "What is Urbit?" video (which I have not linked, in case someone's looking to get me in trouble..!). The design language and presentation of the high level concepts in the video is clearly quite superb; a similar vision could be applied to the Urbit documentation to make it not only easier to understand Urbit holistically (which technically difficult and technically necessary) but also easier to navigate and dive down into details fluidly without losing sight of Urbit's glorious entirety. After all, we humans are "better than we think" with complex pattern recognition, right?

I'm no graphic designer, but my initial vision here (and I haven't thought much about this) is to present the docs with the circle, just as it is in the video. Urbit really vibes with the circle, man, and the actual architecture is astonishingly concentric isn't it? Each of the layers of the circle (and subsequent pie-like partitions of layers) should be expandable, zoomable if you will, thereby focusing the kernel module or concept at hand. And though a user might be focusing on the center at the moment, checking out the Nock definition, they'd never lose sight of Nock's role in Urbit as a whole because the Urbit pie, so to speak, has just been shrunk, slightly desaturated, and moved to the top of his screen... or something like that!

Honestly, Urbit is quite beautiful, the more you learn about it. The docs are beautiful too, but I don't think they yet do justice. What do you guys think? Also, where's the guy who built all those awesome Urbit interface mockups?

[belisarius222]

@cgyarvin I'm down.

@joshuareagan I do think the docs should be largely self-contained. Even the type system is unusual enough that comparisons to other type systems are likely to be misleading. It's fine to have a few references to external concepts (e.g. "type system"), but I think the main difficulty learning hoon is the number of internal concepts. You and Curtis are both right that I should put my money where my mouth is and make this.

@mattlevan I don't know what you're smoking, but I should get some from you to ease the comedown off all that Adderall. You're right that Urbit is beautiful, and that some of the concepts lend themselves to visual descriptions, especially for more holistic introductions. In fact, I think a visual layout of a core (battery, sample, context) will be a crucial pedagogical instrument. Also, a visual representation of swapping the sample to slam a gate (%-, "call a function") or to open a door (%~) will help people learn hoon quickly. As for representing the docs themselves as zoomable concentric pie slices, I suspect a more standard layout would work better as a navigation tool, but I'd be happy to be proven wrong about that. Diagrams of the Urbit stack might very well want to use that kind of layout, and maybe an interactive d3 graphic like this would be worthwhile.

As for your other questions:

• I think Galen, the Tlon CEO, built the interface mockups.
• The docs, like many parts of the system, aren't kelvin versioned because they're not ready to freeze. See this fora post for more details.

[joshuareagan]

@belisarius222 In some sense I agree that the docs should be self-contained, but this is a bit ambiguous; and in any case it's one virtue we have to weigh against others.

Thankfully we're not committed to one set of trade-offs. We can have different learning paths, and your doc idea would be great for one of those. OTOH, I think that the current Hoon and Arvo doc series cover a different but nevertheless legitimate angle to learning about Urbit. (Do they always do it well? That's a separate question.)

One thing to disambiguate:

(a) Urbit has a lot of concepts that are particular to Urbit, so we name them accordingly. Does Urbit earn its year 0 vocabulary? Arguably it does. I make no objection to there being new terms for Urbit concepts that don't map well to non-Urbit concepts.

(b) How much non-Urbit terminology are we to use when explaining Urbit concepts in documentation aimed at (Urbit) beginners? Being a stickler here just seems cruel to me. At the extreme we'd invent a new language for Urbit altogether, and when we write "gavagai" in the docs readers have to guess whether we mean "rabbit" or "undetached rabbit part". (https://en.wikipedia.org/wiki/Indeterminacy_of_translation)

It's pedagogical malpractice not to take advantage of intuitive explanations in our docs. We must balance the strict accuracy of an explanation with how long it takes for a reader to develop the correct mental model. Having an imperfect but decent first-order approximation of a concept arguably makes it easier to get to true knowledge; and it is probably faster too.

[cgyarvin]

All I can say is that this is a hard problem and I welcome creative new thinking about it. :-)

On Thu, Oct 5, 2017 at 3:12 PM, Joshua Reagan notifications@github.com wrote:

@belisarius222 https://github.com/belisarius222 In some sense I agree that the docs should be self-contained, but this is a bit ambiguous; and in any case it's one virtue we have to weigh against others.

Thankfully we're not committed to one set of trade-offs. We can have different learning paths, and your doc idea would be great for one of those. OTOH, I think that the current Hoon and Arvo doc series cover a different but nevertheless legitimate angle to learning about Urbit. (Do they always do it well? That's a separate question.)

One thing to disambiguate:

(a) Urbit has a lot of concepts that are particular to Urbit, so we name them accordingly. Does Urbit earn its year 0 vocabulary? Arguably it does. I make no objection to there being new terms for Urbit concepts that don't map well to non-Urbit concepts.

(b) How much non-Urbit terminology are we to use when explaining Urbit concepts in documentation aimed at (Urbit) beginners? Being a stickler here just seems cruel to me. At the extreme we'd invent a new language for Urbit altogether, and when we write "gavagai" in the docs readers have to guess whether we mean "rabbit" or "undetached rabbit part". ( https://en.wikipedia.org/wiki/Indeterminacy_of_translation)

It's pedagogical malpractice not to take advantage of intuitive explanations in our docs. We must balance the strict accuracy of an explanation with how long it takes for a reader to develop the correct mental model. Having an imperfect but decent first-order approximation of a concept arguably makes it easier to get to true knowledge; and it is probably faster too.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/137#issuecomment-334606689, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAePRPHXkj3OyZugob2ox7qqm0sL1ks5spVRRgaJpZM4L7rbj .

[joshuareagan]

Agreed, it's definitely hard. I'll do my best!

[belisarius222]

I guess that's what I get for trying to debate a logician :) @joshuareagan the more you tell me about Quine, the cooler his work seems.

As for the accuracy / intuitiveness tradeoff, I don't think we're anywhere near the Pareto frontier with our current docs, so I'm not too concerned. Also, why would I care, "gavagai" isn't even four letters!

I'm not sure we merit the Year 0 vocabulary currently. At least by Year 3 it pays off (cf. Mr. Dyudin), but Year 3 worthiness isn't affected too strongly by the docs.

When explaining concepts I generally try to say everything at least two times, in different ways, to minimize the indeterminacy. I think I started doing that after reading about the parallel sentences in the Confucian eight-legged essay format. Adding another explanation that references some external concept can be quite helpful. When combined with a "self-contained" explanation, I don't think there's much harm from the comparison, especially if the degree of similarity is made explicit.

Here's an example of how I think these two styles can be used synergistically:

A gate is a core with just one arm, called $ (the empty symbol), and the irregular syntax (gate-name argument) will "slam" the gate with that argument. Slamming a gate replaces the sample (+<) of the gate with argument, and then evaluates the $ arm in this new modified core, producing the result. When this is performed, the new sample must "nest" inside the span of the default sample. The new sample is also cast to the span of the default sample. It's also possible to "bunt" a gate, which evaluates the $ arm with the default sample. A gate can be bunted by surrounding it in parentheses (gate-name) or preceding it by *: *gate-name.

A gate is like a lambda or closure in other languages, except that it also includes its evaluation context (+>) and a default argument (+<), which must be 'swapped out' with the actual value to be called, unless the gate is bunted, in which case the default sample is used. Bunting a gate doesn't have a direct analog in other computer systems. The term is borrowed from baseball, where it means to take the minimum possible swing at a ball, instead of the normal attempt to hit it as far as possible. Bunting a gate is something like making the minimum possible attempt at calling a function, avoiding the usual pattern of giving it an argument. Another difference between gates and closures in most languages is that the data structure used in nock and hoon to represent a gate is available to the programmer for direct access and "modification" (mutant copying).

[joshuareagan]

I don't think we're all that far apart.

[belisarius222]

I agree :)

[dustinb]

Thoughts from a "developer" in the trenches trying to learn hoon: I think the idea of 3 ways to learn is well intentioned but I find myself getting lost in the docs. The main way I get lost is I'm going through a section and I realize I don't know what I thought i knew or I lost the concept of something in the maze of twigs. The difficult part is I can't recall where I first learned" that concept, was it the quick start, hoon area, examples area, contributors docs?

My opinion is a single entry point explaining concepts using with a standard table of contents would be best. Either way you learn the areas where you learned it should be consistent? Not sure if it's possible to describe something bottom up or top down using the same entry points from a standard TOC.

As far as linking familiar terms I would say best not to do it. I think if it's done too much people like myself will start using the familiar terms when asking for help or continually thinking about the concepts in these familiar ways. If it is done, do it in a drive by manner. "A gate is similar to a function" and then never mention function ever again. Kinda like when a kid swears, you hear it but don't pay it any attention and carry on like it didn't happen. Give it too much attention and that swear word becomes common language.

[cgyarvin]

All good perspectives. There is really no perfect answer here.

On Wed, Nov 8, 2017 at 10:53 AM, Dustin Butler notifications@github.com wrote:

Thoughts from a "developer" in the trenches trying to learn hoon: I think the idea of 3 ways to learn is well intentioned but I find myself getting lost in the docs. The main way I get lost is I'm going through a section and I realize I don't know what I thought i knew or I lost the concept of something in the maze of twigs. The difficult part is I can't recall where I first learned" that concept, was it the quick start, hoon area, examples area, contributors docs?

My opinion is a single entry point explaining concepts using with a standard table of contents would be best. Either way you learn the areas where you learned it should be consistent? Not sure if it's possible to describe something bottom up or top down using the same entry points from a standard TOC.

As far as linking familiar terms I would say best not to do it. I think if it's done too much people like myself will start using the familiar terms when asking for help or continually thinking about the concepts in these familiar ways. If it is done, do it in a drive by manner. "A gate is similar to a function" and then never mention function ever again. Kinda like when a kid swears, you hear it but don't pay it any attention and carry on like it didn't happen. Give it too much attention and that swear word becomes common language.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/urbit/docs/issues/137#issuecomment-342921563, or mute the thread https://github.com/notifications/unsubscribe-auth/AALyAUESKKnry5htmHg33BeS8KaXnpTHks5s0fi5gaJpZM4L7rbj .

[xykj61]

I think we agree that in the upcoming docs rewrite, this issue needs to be addressed. Closing this for now, as there are no immediate next actions, but adding the 'rewrite' label so we can reference this later.