[urbit] Re: [joemfb/docs] Merged glossary (#4)

[c***@gmail.com]

I guess the question we have to ask is: what criterion, rigorous or not, determines admission to the glossary?

Also, it's a rather odd glossary in that it's organized topically instead of alphabetically.

I guess I'm just seeking the vision for this document. Anyone? I didn't create it so it can't be my vision...

Sent from my iPhone

Perfect, I've pulled your changes and updated urbit/docs#34.
There's a handful of other terms I'd like to get in (alias, bridge, vase, etc.), but those are probably best handled in separate PRs to urbit/docs. This has already been a pretty convoluted effort.
Anyway, I'll make those arguments in more detail separately.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[Joseph Bryan]

(link for urbit-dev: https://github.com/urbit/docs/pull/34)

Fair enough. I created the initial document - here's why, and how*:

I've read just about everything I can find on Urbit, and the conceptual
density is overwhelming. http://novlen-hanweb.urbit.org/easy.html is a
cruel caricature, but it captures the feeling nonetheless - somebody
quipped that Urbit nullifies the advantages that English-speaking
programmers have traditionally enjoyed ...

More importantly, while the terms are (almost) all defined somewhere, that
somewhere is distributed across hundreds of pages of documentation. I found
myself switching between dozens of tabs to puzzle through a sentence**. I
eventually cloned the docs and resorted to grep. As i found the best
definitions in the docs, I copied them into my notes. I compiled the notes,
and left TODOs for definitions I couldn't find (@asgardiator has since
filled those in).

I should note that, until recently, I hadn't actually worked through the
Arvo tutorials and Hoon exercises. That would've been a better approach;
concrete -> abstract always trumps the inverse, but I was lazy, and tried
to side-load the concepts first.

I found it useful to have a single document that defined important
concepts, with contextual links to the relevant sections of the docs. It's
useful as a reference when reading the docs, but also on its own; concisely
defining and relating key terms. I organized it topically rather than
alphabetically; one concept begets another, and "stem" or "bulb" (for
instance) seem less deserving of prominence then "core" or "mold".

Maybe it should be called something other than a glossary: a concordance?
Folksonomy? It's kind of an unusual document, but it is about Urbit ... ;)

I found creating it to be an educational exercise, and hope it's useful to
others as well. Maybe it'd be more useful (or better suited to the official
documentation) if it were structured as a flat, alphabetical glossary -
that's not a call I can make. I'm happy to work on restructuring it if
you'd like.

And as for the admission criteria, here's my best guess: if a term is a) an
Urbit term-of-art and b) used elsewhere in the docs, it should probably be
included (gates and cores in the standard library should probably be exempt
from that, unless their names are also general Urbit/Hoon concepts).

Thanks.

-jb

*history rebased for narrative coherence
**possibly a slight exaggeration

Post by c***@gmail.com
I guess the question we have to ask is: what criterion, rigorous or not,
determines admission to the glossary?
Also, it's a rather odd glossary in that it's organized topically instead
of alphabetically.
I guess I'm just seeking the vision for this document. Anyone? I didn't
create it so it can't be my vision...
Sent from my iPhone
Perfect, I've pulled your changes and updated urbit/docs#34
<https://github.com/urbit/docs/pull/34>.
There's a handful of other terms I'd like to get in (alias, bridge, vase,
etc.), but those are probably best handled in separate PRs to urbit/docs.
This has already been a pretty convoluted effort.
I do, however, have a defense of the inclusion of tape - at least
*somewhere*. it's privileged with two (2) forms of syntax, and it's the
more natural string type for programmers coming from high-level languages
which is why I stuck it with atom ...
Anyway, I'll make those arguments in more detail separately.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<https://github.com/joemfb/docs/pull/4#issuecomment-226655289>, or mute
the thread
<https://github.com/notifications/unsubscribe/AALyAcYPPsSbto6Y0zx-KDzwIjEEkBAbks5qMfExgaJpZM4I201D>
.
--
You received this message because you are subscribed to the Google Groups "urbit" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

[Jeremy Wall]

I just want to say that as someone who did the hard work of figuring all
this stuff out himself that easy link is Hilarious!

Post by Joseph Bryan
(link for urbit-dev: https://github.com/urbit/docs/pull/34)
I've read just about everything I can find on Urbit, and the conceptual
density is overwhelming. http://novlen-hanweb.urbit.org/easy.html is a
cruel caricature, but it captures the feeling nonetheless - somebody
quipped that Urbit nullifies the advantages that English-speaking
programmers have traditionally enjoyed ...
More importantly, while the terms are (almost) all defined somewhere, that
somewhere is distributed across hundreds of pages of documentation. I found
myself switching between dozens of tabs to puzzle through a sentence**. I
eventually cloned the docs and resorted to grep. As i found the best
definitions in the docs, I copied them into my notes. I compiled the notes,
filled those in).
I should note that, until recently, I hadn't actually worked through the
Arvo tutorials and Hoon exercises. That would've been a better approach;
concrete -> abstract always trumps the inverse, but I was lazy, and tried
to side-load the concepts first.
I found it useful to have a single document that defined important
concepts, with contextual links to the relevant sections of the docs. It's
useful as a reference when reading the docs, but also on its own; concisely
defining and relating key terms. I organized it topically rather than
alphabetically; one concept begets another, and "stem" or "bulb" (for
instance) seem less deserving of prominence then "core" or "mold".
Maybe it should be called something other than a glossary: a concordance?
Folksonomy? It's kind of an unusual document, but it is about Urbit ... ;)
I found creating it to be an educational exercise, and hope it's useful to
others as well. Maybe it'd be more useful (or better suited to the official
documentation) if it were structured as a flat, alphabetical glossary -
that's not a call I can make. I'm happy to work on restructuring it if
you'd like.

The topical organization causes a fair amount of overlap with the existing
documentation. An alphabetical listing gives more value turning this into a
place where you go to find the definition of a term you encountered
elsewhere. The alphabetical organization would just make lookup faster.

Post by Joseph Bryan
And as for the admission criteria, here's my best guess: if a term is a)
an Urbit term-of-art and b) used elsewhere in the docs, it should probably
be included (gates and cores in the standard library should probably be
exempt from that, unless their names are also general Urbit/Hoon concepts).
Thanks.
-jb
*history rebased for narrative coherence
**possibly a slight exaggeration

Post by c***@gmail.com
I guess the question we have to ask is: what criterion, rigorous or not,
determines admission to the glossary?
Also, it's a rather odd glossary in that it's organized topically instead
of alphabetically.
I guess I'm just seeking the vision for this document. Anyone? I didn't
create it so it can't be my vision...
Sent from my iPhone
Perfect, I've pulled your changes and updated urbit/docs#34
<https://github.com/urbit/docs/pull/34>.
There's a handful of other terms I'd like to get in (alias, bridge, vase,
etc.), but those are probably best handled in separate PRs to urbit/docs.
This has already been a pretty convoluted effort.
I do, however, have a defense of the inclusion of tape - at least
*somewhere*. it's privileged with two (2) forms of syntax, and it's the
more natural string type for programmers coming from high-level languages
which is why I stuck it with atom ...
Anyway, I'll make those arguments in more detail separately.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<https://github.com/joemfb/docs/pull/4#issuecomment-226655289>, or mute
the thread
<https://github.com/notifications/unsubscribe/AALyAcYPPsSbto6Y0zx-KDzwIjEEkBAbks5qMfExgaJpZM4I201D>
.
--
You received this message because you are subscribed to the Google Groups "urbit" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "urbit" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

--
Jeremy Wall
http://jeremy.marzhillstudios.com
***@marzhillstudios.com