Choosing the final layout

[Saïvann Carignan]

Since we're getting closer to publishing this, now might be a good time to start discussing about what should be the final structure and layout.

In particular, should we use a single page layout or split everything into multiple pages (or else even do both)?

In general, I think we should try finding the best structure for existing and future requirements.

For instance, what type of content is likely to be added over time? Will it be more examples, walkthrough? How can we fit this future content while keeping the documentation clear, organized and duplicate-free?

Since we're already working with a single-page layout, I've just made a multi-page layout draft so we have at least one example:

http://bitcoindevsplit.us.to/en/developer-guide

Feedback, ideas, suggestions welcome.

[Mike Hearn]

I prefer the multi-page layout for sure. It allows the front page to be perhaps more active/alive, and have more images. For instance, there could be casual / one-off articles written for a developer audience that get highlighted on the front page, like a blog, links to developer services, etc. Not for v1 sure but in future.

--
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.

[David A. Harding]

On Tue, Apr 15, 2014 at 10:06:28PM -0700, Saīvann Carignan wrote:
> Since we're getting closer to publishing this, now might be a good time to
> start discussing about what should be the final structure and layout.

I think we should be careful about trying to fit all of our
documentation into one mold. I think we should aim for following four
types of documentation commonly seen for mature software platforms:

1. Developer Guide: "read this and you'll understand how Bitcoin works
well enough to start developing for it." Like an O'Reilly *Learning
(language)* programming book.

2. Developer Reference: "skim this to find specific protocol/API
details". Like the back parts of an O'Reilly *(language)* book (or
maybe like an O'Reilly pocket guide).

3. Developer Cookbook: "skim this to get code you can quickly adapt to
your purpose." Like an O'Reilly *(language) Cookbook*.

4. Specific-issue docs which draw from one or more of the above three
sources (and external references) to put all the information on one
page for that specific issue, like a quality blog post.

For usability, I think the following forms make the most sense:

1. The Developer Guide should be easy to read from beginning to end so
developers don't miss important points.

2. The Developer Reference should be easy to search and navigate so
developers can quickly find the details they need.

3. The Developer Cookbook should also be easy to search and navigate
so developers can quickly find the code samples/design patterns
they need.

4. Specific-issue docs should probably actually be a blog on a subdomain
so that we can post frequently about possibly-basic stuff without
spamming the core devs watching the bitcoin.org repo.

With four separate sections, we'd certainly need a landing page, which
could look a lot like the one Saīvann posted earlier.

So, my thought is that we keep the current developer guide on one page
for easy reading but that we start moving reference sections and
cookbook-style examples to different pages and figure out how to index
them well.

Feedback appreciated,

-Dave
--
David A. Harding

[Saïvann Carignan]

That's very interesting suggestions!

One important limitation here IMO is that we're not grouping content
(guide, reference, cookbook, specific-issue docs) by "categories"
(transaction, contracts, wallets, etc) with this approach.

The more I think about it, the more I'm tempted to explore your previous
email suggestion of providing both full guides and split sections, using
clever {% include %} rules. So we can do both what you've just
mentioned, and still have something similar to the example layout I've
just provided.

It also seems to me like "4. specific-issue docs" would be better served
only as articles displayed under each category (transaction, contracts,
wallets, etc).

As a more visual example, the portal page could look like:

--------------------------

Developer guide | Developer Reference | Developer Cookbook

--------------------------

Block Chain | Transactions
|
Guide | Guide
Reference | Reference
Examples | Examples
More.. | More..
|
--------------------------
Contracts | Wallets
|
Guide | Guide
Reference | Reference
Examples | Examples
More.. | More..
|

--------------------------

Etc.

Saïvann

[David A. Harding]

On Wed, Apr 16, 2014 at 03:10:38PM -0400, Saīvann Carignan wrote:
> I'm tempted to [provide] both full guides and split sections, using
> clever {% include %} rules. So we can [have several doc types], and

> still have something similar to the example layout I've just provided.

If I understand you correctly, I like it. To rephrase based on my
understanding, our source would look like this:

block_chain_guide.md
block_chain_ref.md
block_chain_cookbook.md
tx_guide.md
[...]

The complete_guide.md file would look like this:

{% include block_chain_guide.md %}
{% include tx_guide.md %}
[...]

The complete_ref.md file would like like this:

{% include block_chain_ref.md %}
{% include tx_ref.md %}
[...]

Ditto for the complete_cookbook.md.

Your landing page links would then point to either the individual
rendered [section]_[type].md files or the relevant #[section] in the
rendered complete_[type].md files.

Is that understanding correct? If so, +1.

[Saïvann Carignan]

Yes, something like that.

Since the table of content needs to be rendered once for each page, the
content could actually be moved under _devdocs/

> _devdocs/block_chain_guide.md
> _devdocs/block_chain_ref.md
> _devdocs/block_chain_cookbook.md
> _devdocs/tx_guide.md

And each template in /en/* would just {% include %} this content as
needed. (Still needs to be tested though).

Saïvann

[David A. Harding]

On Wed, Apr 16, 2014 at 04:29:30PM -0400, Saīvann Carignan wrote:
> Yes, something like that.

Cool. I like it.

> Since the table of content needs to be rendered once for each page, the
> content could actually be moved under _devdocs/

I think the doc I read about {% include %} said all included parts need
to be under _include or something anyway. I guess one of us should test
`include` before we do too much more planning based on how we *think* it
should work.

Thanks, Saīvann!

[Saïvann Carignan]

Le 2014-04-16 16:37, David A. Harding a écrit :

> I think the doc I read about {% include %} said all included parts need
> to be under _include or something anyway. I guess one of us should test
> `include` before we do too much more planning based on how we *think* it
> should work.

Exactly :) I'm definitively going to test this more. Thanks!

(If anyone also have some thoughts or ideas to share, please share them,
this is still "brainstorming" and work-in-progress.)

Saïvann

[Chris Beams]

One thing to consider with a multi-page layout is that searching across all pages becomes more difficult. In the single-page approach a reader can use "Find" within the browser to search for all instances of a given term and easily iterate through them. Achieving something similar in the multi-page approach requires offering integrated search functionality (which bitcoin.org does not currently have). In its absence, the user must resort to techniques like Google "site:" queries.

For a concrete example, consider a reader of the multi-page guide who wishes to understand the meaning of the term "coinbase". While the main explanation is currently located in the Block Chain section, it is mentioned in two other sections as well (Transactions and Wallets). A user encountering this term in the Transaction section could click on the word and be taken to its main explanation in the Block Chain section, but would still remain unaware of its mention in the Wallet section.

[Saïvann Carignan]

That's a good point. When it comes to printing, having only specific subsections is handy. All in all, that personally further convince me that having both is a good idea.

TBH, I doubt bitcoin.org will have a search bar anytime soon as we're trying to be paranoid regarding security and serve static content so the binaries remain as safe as possible.

Saïvann

[David A. Harding]

On Thu, Apr 17, 2014 at 09:02:27PM -0700, Saīvann Carignan wrote:
> having both is a good idea.

That raises a related question: if we have both, which version should we
prioritize in search results? (I.e. which version should we make
canonical[1]?)

[1] https://support.google.com/webmasters/answer/139066

Let's a assume the reader searches Google for "locktime". They can then
land on either the full version (one page) of the guide or the Tx page
of the complete (split pages) guide, or even (if we go that route), the
Locktime And Sequence (LT&S) subsection page of the Tx section of the
complete (many split pages) guide.

* Full page: user starts at introduction, which has nothing to do with
locktime, and must either scan the page or use C-f to find the part
about locktime. But, having used C-f, the user will also see the use
of locktime throughout the rest of the document.

* Tx page: user still has to navigate a fair amount of until getting to
the locktime part, either by skimming or using C-f. They'll learn the
details about locktime but they won't (with our current links) see
anything about how it's used in micropayment channels.

* LT&S page: user jumps straight to the information they searched for,
but they don't get any of the non-locktime-section text about how
locktime fits into txes, such as the illustration at the top of the Tx
section or the fact that signatures always sign locktime.

The final concern is how good Google will be about recommending the most
relevant page. Locktime gets a lot of mentions in the Locktime
subsection of Txes, of course, but it also gets a lot of mentions in the
Contracts section. If Google only recommends one of our split pages, it
could be the page that's less useful for the user.

I'm not sure what the right solution is.

[Saïvann Carignan]

Canonicalization is even a little more complex here (we're duplicating
partial content, not full content), and yes, I agree that duplicate
content brings issues. Another one is that people will link to two
different versions of the same page, which also affects search results.

Perhaps the suggested layout could just link to anchors within the three
single-page documents you suggested (no duplicate split pages), and this
would be a good compromise without the drawbacks mentioned above. This
solution would still be as scalable and allow some organized place for
specialized articles and additional content.

As far as I know, Google detects and uses anchors correctly. In your
example, I wouldn't be surprised that Google would provide more
visibility to
http://bitcoindev.us.to/en/developer-guide#locktime-and-sequence-number
since "locktime" is part of the url, and a people might link to it
directly over time, further improving search results.

Not to forget your crosslink reference feature, which actually tells a
lot of information to Google too.

Saïvann

[David A. Harding]

Within the next 48 hours, I'd like to finalize the plan for the final
layout for the first version of the guide (which I've been calling
v0.1). Here is the proposal as we last discussed it:

Web pages will be:

* /en/developer-guide (currently 80 printed pages long)

Devguide: An overview of Bitcoin technology to introduce developers to
the building blocks they can combine together to create applications.
Will link to devguide for details unnecessary in an overview and
devcookbook for lengthy examples.

One webpage for easy in-browser (C-f) searching.


* /en/developer-reference (estimated to be about 15 printed pages in v0.1)

Devref: A quick source of precise technical information. Will link
to devguide for background explanations and devcookbook for
lengthy examples.

One webpage for easy in-browser (C-f) searching.


* /en/developer-cookbook (not part of v0.1)

Devcookbook: A collection of reusable or easily reimplemented code
examples for common tasks, along with explanations of the tasks and
the code. Will link to devguide for background explanations and
devref for technical details.

May be one page or multiple pages, and will probably be integrated
with a git code repository. We don't need to decide for v0.1.


* /en/developer-docs (not created yet)

Devportal: will include links to each of the h2 sections in the
devguide, devref, and devcookbook. Links will be grouped by topic
(such as "block chain").


Each page above will be automatically built from several different
source files. Right now, those files are developer-guide.md,
api-reference.md, and _includes/references.md.

By building the large pages from smaller source text, we can later
switch to smaller pages with a minimum of effort, or even have both
large and small pages coexisting with near-100% shared text. However,
for v0.1, we will only have large pages---we'll wait to see what
problems (if any) arise before fully implementing small pages.


That's the proposal, and we'd like to get it coded and tested as soon as
possible, so we'd appreciate it if you respond soon with questions,
criticism, ACKs, or LGTMs.

Thanks,

[Chris Beams]

LGTM in general, but a few specific questions:


1. With regard to versioning, do you intend to actually publish "v0.1" somewhere, or is this just an internal handle? I'll have a couple follow-up questions if the former, never mind if the latter.


2. With regard to paths, have you considered the following, alternative structure?

- /en/developer

Replaces "/en/developer-docs" as described below with an intuitively located landing page containing short descriptions of and links to each of the three main docs below, as well as a 'portal' section with the by-topic h2 cross-references you mentioned.

- /en/developer/guide
- /en/developer/reference
- /en/developer/cookbook

Each of the above correspond to their developer-* counterparts. No content changes, just changes to the path.


3. Closely related to the above, we should probably consider that with the addition of these pages we will now have development-related resources spread across three nav sections:

- /en/bitcoin-for-developers (as linked to from the "Introduction" section of the nav)
- /en/development (as linked to from the "Resources" section of the nav)
- /en/developer* (the new section we're discussing here)

Perhaps we should consider consolidating these pages under a single section.

[Saïvann Carignan]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Le 2014-04-28 17:04, Chris Beams a écrit :

>
> 2. With regard to paths, have you considered the following,
> alternative structure?
>

> - /en/developer/guide - /en/developer/reference -
> /en/developer/cookbook

I suggest we just keep this suffix for all pages /en/developer-*

I doubt this will happen, but using a subdirectory could be a problem
if these pages were translated similarly to the rest of the website in
the future.

> 3. Closely related to the above, we should probably consider that
> with the addition of these pages we will now have
> development-related resources spread across three nav sections:
>
> - /en/bitcoin-for-developers (as linked to from the "Introduction"
> section of the nav) - /en/development (as linked to from the
> "Resources" section of the nav) - /en/developer* (the new section
> we're discussing here)
>
> Perhaps we should consider consolidating these pages under a single
> section.

Each of these pages link to the documentation.

/en/bitcoin-for-developer (translated) only summarizes key interesting
points and is consistent with "Individuals" and "Businesses". I kind
of thought it was good to keep it, but open to suggestions.

/en/development is about Bitcoin Core & other libraries development,
so this page should not be merged/replaced I think.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTXseWAAoJEFeA9dMbVXew8D8IAN4FC0X4EtH+ozUyo828xefQ
fDNdrkv+Mia3OGrNuuKJtqt1SKg5l8nEXYNW5agkvk1tEXavbe+aSUySNSfqLErG
GBfrWBGYhwF13OCGhcWZilUwOxc7UWS9Y/QUhScUtoZdAokkD/kPZ6dI4wCXo7Me
zU+tm06yoIrYD1jYVWL7gdnrxVnOX5hMsz6B41n0ESxid0Dsvujd76YStAsfrC8H
zbpes/5neFo9VteF39G/SIaYWucGITPXTiZUcAUKOzWBzj2V+f/Hh2t4cTc8bGWK
oT+5GlGfxKq2qdjtNW1lDfgWU5ExjGrnMSKvXarttf59yOCwWRms/jeS3v+e0l0=
=eZFC
-----END PGP SIGNATURE-----

[Saïvann Carignan]

Just a suggestion, how about we name/link each page like this?

/en/developer-documentation -> Developer Documentation
/en/developer-guide -> Developer Guide
/en/developer-reference -> Technical Reference
/en/developer-code -> Code Samples

When I tested the layout, this seemed more readable to me on a single line:

"Developer Guide - Technical Reference - Code Sample"

"Developer Guide - Developer Reference - Developer Code"

--

Thank you for getting back to it. I didn't figure out exactly what
should be split and where, I've also been busy in the last days. I'll
provide us with a branch with the portal page a few hours later today so
we can work with it.

Perhaps you can avoid the trouble of splitting this into small files? We
could just keep big guides and link to anchors in them from the portal
page (no duplication of content).

Saīvann

[David A. Harding]

On Mon, Apr 28, 2014 at 11:04:20PM +0200, Chris Beams wrote:
> 1. With regard to versioning, do you intend to actually publish "v0.1"
> somewhere, or is this just an internal handle? I'll have a couple
> follow-up questions if the former, never mind if the latter.

I intended v0.1 to be just an internal handle, as the actual guide will
be part of Bitcoin.org which doesn't have version numbers.

We don't have a workflow planned once v0.1 goes live on Bitcoin.org.
Without thinking about it too hard, I think it might be easiest to
submit pull requests against the Bitcoin.org repo only for error
corrections and other small-but-important updates. Brand new or
substantially revised content would be publish to Saļvann's repository
the same way we do now and then merged en masse every month or so. That
way we don't overwhelm the Bitcoin.org watchers with minutia.

> 2. With regard to paths [...]

(Answered by Saļvann. I highly recommend against translation of v0.1,
but I would like to make it easy to translate later versions of the
devguide, devref, and devcookbook.)

> 3. Closely related to the above, we should probably consider that with
> the addition of these pages we will now have development-related
> resources spread across three nav sections:

(I agree with Saļvann's thinking on this.)

[David A. Harding]

On Mon, Apr 28, 2014 at 05:38:03PM -0400, Saīvann Carignan wrote:
> Just a suggestion, how about we name/link each page like this?
>
> /en/developer-documentation -> Developer Documentation
> /en/developer-guide -> Developer Guide

These look fine to me.

> /en/developer-reference -> Technical Reference
> /en/developer-code -> Code Samples

This isn't particularly important to me, but I prefer page names which
correspond to URLs, so "Developer Reference" and "Developer Code"
seem better.

Actually, Developer Code doesn't sound good to my ear. If you don't like
Developer Cookbook, maybe we should call it "Developer Examples" with
/en/developer-examples. Examples is also more descriptive, since we'll
probably have non-code examples, such as howtos for setting up a testing
environment. (Either way, let's not spend much time on it now since it
doesn't matter for v0.1.)

> When I tested the layout, this seemed more readable to me on a single line:
>
> "Developer Guide - Technical Reference - Code Sample"
> "Developer Guide - Developer Reference - Developer Code"

Are these links being automatically created? If not, the repeated
element can be dropped:

"Guide - Reference - Examples"

> I'll provide us with a branch with the portal page a few hours later
> today so we can work with it.

If possible, I suggest you code it for just the Guide and Reference
parts as it'll probably be at least another two months before we have
any substantial content for Examples.

> Perhaps you can avoid the trouble of splitting this into small files? We
> could just keep big guides and link to anchors in them from the portal
> page (no duplication of content).

Right, sorry, I thought I mentioned that we wouldn't be creating small
files for v0.1. I just wanted to mention that we can do that at any
point without any significant extra maintenance burden, so people who
aren't happy with large pages don't have to worry about us going down a
hard-to-reverse path.

[David A. Harding]

Saīvann and I put together a functional preview of the new landing page
and Developer Reference:

http://bitcoindevsplit.us.to/en/developer-documentation

(Note: lots of links are broken by this preview renaming/rearrangement.
They'll be fixed and checked before the release.)

There's still work to be done, but that's the basic approach we plan to
take for v0.1. If you object to that approach, please reply to this
email within the next 24 hours (or wait until we start planning v0.2).

Comments on ways to tweak the layout above should be posted to the pull
request:

https://github.com/saivann/bitcoin.org/pull/88

Thanks,