Create Dev Docs Glossary, Or Extend Vocabulary Page

[David A. Harding]

Hi all,

Very early in the initial writing of the documentation, we briefly
discussed[1] adding a glossary or extending the Vocabulary page[2]. Our
conclusion, as stated by Saīvann and explicitly agreed to by me, was:

> we can perhaps review this once we have the first draft and see what
> improvements can be done (e.g. [...] use / update the vocabulary page)

Later, when we decided to use the everything-on-one-big-page format, one
of the reasons given was that it made it easy for searchers to use their
browser's Find-On-Page feature to find particular terms. Since we
provide extensive internal cross-referencing of terms to the point where
they get defined, readers finding any instance of a term can get a
definition with either a simple hover or click.

Because that format seems to be working, we've never revisited the
question of a glossary. However, Peter Todd brought up a use for a
glossary in pull #566[3]---the ability of a glossary to easily define
synonyms, such as "scriptSig" and "signature script" meaning the
same thing.

For that specific example, we already try to do the same in the text at
the point signature script is defined: "Signature scripts are also
called scriptSigs." I think we've always tried to do that---for example,
see issue #455[4] where we added a reference to "nLockTime" in the section
about "locktime" to help people searching for nLockTime.

I think consistent use of this define-synonyms-at-introduction formula
eliminates the need for a glossary on the webpage, but we should
probably discuss it as we said we would back in March to see if we
still all agree.

-Dave

[1] Previous discussion of a glossary, started March 15th:
https://groups.google.com/forum/#!searchin/bitcoin-documentation/vocabulary/bitcoin-documentation/usWfAprZjwA/HYRbj8kancwJ

[2] Current vocabulary page: https://bitcoin.org/en/vocabulary

[3] ScriptSig vs. signature script, etc pull:
https://github.com/bitcoin/bitcoin.org/pull/566

[4] Add nLockTime issue:
https://github.com/bitcoin/bitcoin.org/issues/455
--
David A. Harding

[Saïvann Carignan]

Sorry for my late reply, and thanks for digging up all previous
discussions about this.

I wonder if it would make sense to keep the existing system, and
generate a glossary page (as in a ordered list of terms, with the usual
devel-guide layout) that would only provide a very short definition of
each term, (the one we have in _includes/reference.md?), and a "Read
more" link pointing to the appropriate text on devel-guide?

People are used to glossaries / dictionaries, and IMO that provides a
handy experience for finding a definition, yet nothing is better when it
comes to explaining things in their context than a complete guide like
what we have now, so I wonder if we can't somehow have the best of both
worlds with the suggestion above.

I also thought about dropping some technical words in the translated
vocabulary page recently (Signature, Private key, Hash rate, Double
spend), to alleviate translations, keep it simple for non-technical
users, and manage technical stuff in devel-doc.

Saïvann

[David A. Harding]

On Sun, Nov 02, 2014 at 09:22:20PM -0500, Saīvann Carignan wrote:
> I wonder if it would make sense to keep the existing system, and
> generate a glossary page

I was mildly against a glossary page in the OP in this thread, but
I've changed my mind. Back when 90% of our documentation was in the
developer guide, it was easy enough to C-f find a term---but now the
developer reference is getting longer and containing more definitions,
meaning readers would need to search two separate pages.

> (as in a ordered list of terms, with the usual devel-guide layout)

Whatever we do, I think we'd need a slight alteration to the layout, as it doesn't work
well for long lists. See how the RPCs run off the page and don't
autoscroll in the devref:

https://bitcoin.org/en/developer-reference#remote-procedure-calls-rpcs

> that would only provide a very short definition of
> each term, (the one we have in _includes/reference.md?), and a "Read
> more" link pointing to the appropriate text on devel-guide?

That sounds reasonable to me. I think I'd also like to have definitions
point to other definitions or sources. For example:

Signature script:

Data generated by a spender which is almost always used as
variables to satisfy a pubkey script. ([Read more])

See also: [pubkey script], [script], [input], [Bitcoin Wiki
article about script].

It seems to me that the right way to do this is to create a YAML file
that contains all the data and then use a plugin to convert that into
the data for both the reference links and the glossary page. That way
our glossary definitions and link definitions stay in sync.

-Dave
--
David A. Harding

[Saïvann Carignan]

> That sounds reasonable to me. I think I'd also like to have definitions
> point to other definitions or sources. For example:
>
> Signature script:
>
> Data generated by a spender which is almost always used as
> variables to satisfy a pubkey script. ([Read more])
>
> See also: [pubkey script], [script], [input], [Bitcoin Wiki
> article about script].
>
> It seems to me that the right way to do this is to create a YAML file
> that contains all the data and then use a plugin to convert that into
> the data for both the reference links and the glossary page. That way
> our glossary definitions and link definitions stay in sync.

I like the idea!

I guess whoever is first available to work on this can comment here (to
make sure we don't duplicate effort).

I may have time to work on this soon, but if someone can overtake me on
this, you're welcome!

Saïvann

[David A. Harding]

On Fri, Nov 07, 2014 at 02:16:09PM -0500, Saīvann Carignan wrote:
> Harding wrote:
> > It seems to me that the right way to do this is to create a YAML file
> > that contains all the data and then use a plugin to convert that into
> > the data for both the reference links and the glossary page. That way
> > our glossary definitions and link definitions stay in sync.
>
> I like the idea!
>
> I guess whoever is first available to work on this can comment here (to
> make sure we don't duplicate effort).

I plan to start working on it this weekend, if nobody has any
objections.

[Saïvann Carignan]

> I plan to start working on it this weekend, if nobody has any
> objections.

Awesome, thanks!

I think this could also be used as a reasonable solution to close #593
https://github.com/bitcoin/bitcoin.org/pull/593

By having a glossary, it would be more easy to pick whatever more
popular lingo without much incidence, given that people people would
easily find definitions and synonyms for each words.

Saïvann

[David A. Harding]

On Fri, Feb 06, 2015 at 03:38:18PM -0500, Saīvann Carignan wrote:
> > I plan to start working on it this weekend, if nobody has any
> > objections.
>
> Awesome, thanks!

Finally done. PR is here:

https://github.com/bitcoin/bitcoin.org/pull/793

Preview is here:

http://dg0.dtrt.org/en/developer-glossary

> I think this could also be used as a reasonable solution to close #593
> https://github.com/bitcoin/bitcoin.org/pull/593

Marked as closed in one of the commits, so it'll close as soon as we
merge.

> By having a glossary, it would be more easy to pick whatever more
> popular lingo without much incidence, given that people people would
> easily find definitions and synonyms for each words.

Indeed. I found writing the synonyms part of the 89 glossary entries nice
for that exact reason.

[Greg Sanders]

Looks very nice!

Greg

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