Systematizing Terminology Introductions And Cross-References

[David A. Harding]

Hi,

The Block Chain section bolds new terms the first time they're used to
help new Bitcoin developers quickly adapt to Bitcoin jargon. I've used
this technique before in other documentation, and readers respond
positively to it.

Other sections don't use this technique, mainly because we haven't
decided how developers will read this document. If they read it in
order, we only need to introduce terms once. If they read only the parts
they need right now, we need to introduce terms separately in each
section.

This leads to a related problem: many terms are defined in one section
but undefined (or loosely defined) in other sections. Ideally, we want
to link an undefined or loosely-defined term to the most complete
definition in the document.

For example, "inputs" and "outputs" are used in the Block Chain section
without being specifically defined; they should probably be linked to
the descriptive definitions which appear later in the Transactions section.

If we do provide descriptive definitions, we need an easy way for us
to link to them. It would also be useful to make it easy for
readers to link to these descriptive definitions in their
own documentation (or Reddit posts).

After playing with Kramdown (our Markdown converter) for a bit, this is
the solution I propose:


1. Near the top of the document, place an invisible alphabetized list of
reference-style links to descriptive definitions[1]. This makes it
clear to writers and editors what links are available. For example:

[block]: #term-block
[input]: #term-input
[merkle root]: #term-merkle-root

2. When we use jargon for the first time in *each section* (header-level
two, h2), we bold it and (if available) link[2] it to the descriptive
definition using the reference-style link. For example:

[...] until a single hash remains, the **[Merkle root][]** of a
**[Merkle tree][].**

3. When we define a term definitively (or at least reasonably well), we
give it an id starting with "term-", a class of ".term"[3], and link
it to itself so readers reading the rendered HTML can easily
right-click copy the link and paste it elsewhere. We also add it
to the list of reference links at the top of the page. For example:

<!-- top of the page -->
[merkle tree]: #term-merkle-tree

<!-- block chain section -->
[...] the [Merkle tree][]{:.term}{:#term-merkle-tree} is constructed
by pairing each [...]


This system solves the problems described earlier without too much
overhead. Specifically:

* Terms will be bolded when the reader first encounters them in each
section, hastening comprehension of Bitcoin jargon.

* Terms will be linked to good definitions, allowing readers to quickly
move to the parts of the documentation they need the most or to open
interesting terms in new tabs for Wikipedia-like non-linear reading.

* Good definitions will link to themselves, allowing other writers to
link to our documentation when they don't want to define things
themselves.

* Our overhead for introducing terms for the first time is just adding
two open-brackets, two close-brackets, and four asterisks[4]. Overhead
for marking a good definition is more complicated, but it only needs
to be done once for each term.


You can see a short patch at the link below which implements the above
ideas on the first paragraph of the Block Chain section. I compiled it
with Jekyll to make sure it works.

https://github.com/harding/bitcoin.org/commit/66d91cafd91b37271e6ff64736aed17259bf8f64

I apologize for the long post, but thank you for reading it. Any
feedback will be appreciated, even if it's just a sounds-good-to-me or
that-sounds-horrible.

-Dave

[1] Immediately after this list of reference links, we can also add any
other commonly-linked resources, such as BIPs. This will make
updating those often-repeated links much easier should the URL ever
change. For example:

[BIP21]: https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
[dev mailing list]: http://sourceforge.net/p/bitcoin/mailman/bitcoin-development/

[2] Saivann can probably style these links specially using CSS such as
"a[href ^="#"]:link.devguide" so readers can visually identify them
as internal links.

[3] Saivann can also style links with a class of .term specially so
readers know that they're self-referencing links.

[4] We could probably drop the bolding and just use whatever styling
Saivann chooses for internal links, which should be enough to
introduce these terms as jargon.
--
David A. Harding

[Saïvann Carignan]

Just tested your branch and proposition and so far I like it!

Actually, why creating self-refencing links? We could just set them in bold and assign them an ID as you're already doing. This way, they'll be used as anchors and people won't click on them.

Saïvann

[David A. Harding]

On Wed, Apr 02, 2014 at 06:47:21PM -0700, Saīvann Carignan wrote:
> Just tested your branch and proposition and so far I like it!

Thanks!

> Actually, why creating self-refencing links? We could just set them in bold
> and assign them an ID as you're already doing. This way, they'll be used as
> anchors and people won't click on them.

I want people to be able to easily link to the terms we link to. For
example, if we have a nice description of merkle trees as used in
Bitcoin and somebody on Reddit wants to link to it, their options are:

1. View the page source code to see what id tag we used.

2. Find somewhere else on the page where we linked to "merkle tree" and
then copy that link.

That's too much work. But if we use a self-referencing link in our
merkle tree description, the reader can just copy it immediately. They
don't need to check source code or go somewhere else on the page.

Does that make sense?

-Dave
--
David A. Harding

[Saïvann Carignan]

Ah, right, that makes sense. Then yes, I should stylize them differently (e.g. display a small anchor/chain icon left to the link).

Le mercredi 2 avril 2014 21:59:22 UTC-4, David Harding a écrit :