WIP: Rewriting the get started flow #136

Mr0grog · 2016-06-01T21:23:41Z

For merging into the general nav restructure or for merging afterwards. This is a work-in-progress branch for writing a new 3 part getting started guide.

This starts with an initial draft of the second step (we've already got the first draft of the first step in learn/get-started/readme.md).

Layout and widget-y stuff will live in https://github.com/stellar/developers. In particular, I need to write up a nice way to present footnotes and the multi-language markup for examples.

Example code is included here in three languages—bash, JavaScript, and Java. I could definitely use feedback on whether the examples show the simplest way to go about doing what they do. The markup looks like:

```md
<example name="Example Name">
```language-name-1
// example code
```

```language-name-2
// example code
```

etc.
</example>
```

bartekn · 2016-06-02T16:25:07Z

learn/get-started/create-account.md

+```java
+// create a completely new and unique pair of keys see more:
+// https://stellar.github.io/java-stellar-sdk/org/stellar/sdk/KeyPair.html
+import org.stellar.sdk.*;


Minor but I'd change to: import org.stellar.sdk.KeyPair;

Heh, I’d originally done that, then switched to this so I didn’t have to write imports in all the subsequent examples :P Will change.

bartekn · 2016-06-03T14:26:59Z

Added Go examples.

Mr0grog · 2016-06-03T15:59:41Z

@bartekn Awesome 👍

Mr0grog · 2016-06-22T15:51:24Z

learn/get-started/create-account.md

@@ -66,7 +66,7 @@ func main() {
 </example>

 [TODO: should this only show if viewing the SDK examples?]
-You might notice that, in the SDK, you ask for the *account ID* instead of the public key. That’s because an account’s ID *is* its public key.
+You might notice that, in the SDK, you are asked for the *account ID* instead of the public key. That’s because an account’s ID *is* its public key.


Hmmm, I think this definitely should have been “ask” instead of “are asked”—at least, I was trying to refer to the fact that you call pair.accountId() or pair.getAccountId() rather than what one might expect from a key pair, e.g. pair.publicKey().

Would if be clearer if it was:

You might notice that, in the SDK, you call pair.accountId() instead of something like pair.publicKey(). That’s because an account’s ID is its public key.

ah, yeah that works also

Mr0grog · 2016-06-22T15:52:39Z

Draft of Sending and Receiving Money, the final step of Get Started. (It only has JS examples for now, so if anybody wants to add Java/Go before I have time to get to it, go for it.)

Footnotes should be `[^number]`, not `[number]`. Our Markdown parser has a bug and needs a blank line between the `<example>` element and the fenced code block. Links to in-site .html files should be to .md files.

… indentation, incorrect smart quotes.

irisli · 2016-06-27T22:34:54Z

learn/get-started/create-account.md

+The first thing you’ll need to do anything on Stellar is an account. Accounts hold all your money inside Stellar and allow you to send and receive payments—in fact, pretty much everything in Stellar is in some way tied to an account.
+
+Every Stellar account has a pair of public and private keys. Stellar uses public key cryptography to ensure that every transaction is secure. The private key is a secret piece of information that proves you own the account. You should never share your private key with anyone. It’s kind of like the combination to a lock—anyone who knows the combination can open the lock. In the same way, anyone who knows your account’s secret key can control your account. The public key is how other people identify your account and verify that you authorized a transaction.
+[TODO: decide on whether we're using public/private or public/secret for keypairs. This doc currently uses both private and secret.]


The correct terminology used by Stellar everrywhere is:

Public Key and Secret Key.

So… this came about because the JS and Java SDKs both don't really expose private keys, only secret seeds:
https://stellar.github.io/js-stellar-sdk/Keypair.html
https://stellar.github.io/java-stellar-sdk/

Some docs talk exclusively about secret seeds (e.g. https://www.stellar.org/developers/learn/get-started/get-started.html) and some talk about both without really clarifying the difference (e.g. https://www.stellar.org/developers/learn/integration-guides/building-blocks/account-management.html). The quick start widget calls the secret seed a private key, which might set someone up for confusion later.

I don't think I've seen a doc that uses "secret key," but maybe I missed it?

Anyway, I think it's important that the secret seed is a different thing from the private key—this actually caused me some personal confusion for a couple days and several wrong steps when trying to use the API and write the original docs. I'm not sure we can just say "secret key" without talking about "secret seed," since seed is the terminology used in most of the SDK APIs.

It might be that I just need to stop and explain both here.

It's because seed is a deprecated term and we haven't taken the time to fix those.

We aspire to use "public key" and "secret key" (we had a big conversation about this a while back).

In practice though, we haven't updated a lot of our code and some stuff even refers to "address".

Better to move forward with the right terms than try to accommodate for the old terms that we are trying to abandon.

…d of a public key.

Mr0grog · 2016-06-28T13:05:33Z

Made some changes in e5a5038 and 4a2ccdf around the descriptions of account IDs, keys, seeds. @irisli @jedmccaleb @jessica-collier how do these read to you, both general clarity and technical accuracy?

Mr0grog · 2016-06-28T13:08:01Z

@irisli @jedmccaleb I think I am also going to drop the Bash examples from the “create an account” doc, since I don’t feel like they add a whole lot and will be inconsistent with “sending and receiving money,” which will never have Bash examples because it would be stupidly complicated. Does that seem alright?

(they are generated when making the site and the duplication is ridiculous.)

irisli · 2016-06-29T18:23:36Z

@Mr0grog Sounds fine to remove bash examples. We don't have any cli tools to build transactions (without invoking one of the js/ruby/go libraries)

irisli · 2016-06-29T23:29:24Z

Using #140 instead so that we merge into master

Mr0grog mentioned this pull request Jun 1, 2016

WIP: General site reorganization stellar-deprecated/developers#65

Merged

First draft of step 2 - create an account.

25a5831

bartekn reviewed Jun 2, 2016
View reviewed changes

Mr0grog added 2 commits June 2, 2016 10:30

Switch to explicit imports in Java examples

1661784

Add link to coinmarketcap's list of exchanges for places to buy lumens.

19d5500

Mr0grog force-pushed the get-started-rewrite branch from 67321b9 to 19d5500 Compare June 2, 2016 18:32

Remove footnote about changing public keys since it was totally wrong!

b0fb037

create-account.md: go examples

7f0676d

Jessica Collier and others added 3 commits June 17, 2016 17:04

Made edits and added TODOs

74e8823

fix typos

a2592a1

Add first draft of get started step 3.

5cf9d6d

Mr0grog reviewed Jun 22, 2016
View reviewed changes

Mr0grog mentioned this pull request Jun 23, 2016

Re-write of guides landing page #139

Merged

Mr0grog added 3 commits June 24, 2016 15:47

Fix footnote and code sample syntax.

445b7ac

Footnotes should be `[^number]`, not `[number]`. Our Markdown parser has a bug and needs a blank line between the `<example>` element and the fenced code block. Links to in-site .html files should be to .md files.

Change <example> to <code-example> to be a proper custom element, fix…

179d956

… indentation, incorrect smart quotes.

Remove old documents from get started flow.

58b3013

irisli reviewed Jun 27, 2016
View reviewed changes

Mr0grog added 2 commits June 27, 2016 23:53

Clean up discussion about getting an account ID from a KeyPair instea…

e5a5038

…d of a public key.

Rework private key/secret seed language in get started flow.

4a2ccdf

Mr0grog added 3 commits June 29, 2016 06:15

Remove title headings from get started docs.

20480cf

(they are generated when making the site and the duplication is ridiculous.)

Make titles active, add back/next buttons everywhere.

50306c7

Remove bash examples from get started

5be16d9

Fix typo in footer

2e1d6ec

irisli mentioned this pull request Jun 29, 2016

Rewriting the get started flow #140

Merged

irisli closed this Jun 29, 2016

irisli deleted the get-started-rewrite branch June 29, 2016 23:36

irisli restored the get-started-rewrite branch June 29, 2016 23:36

irisli deleted the get-started-rewrite branch July 5, 2016 18:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WIP: Rewriting the get started flow #136

WIP: Rewriting the get started flow #136

Uh oh!

Mr0grog commented Jun 1, 2016

Uh oh!

bartekn Jun 2, 2016

Uh oh!

Mr0grog Jun 2, 2016

Uh oh!

bartekn commented Jun 3, 2016

Uh oh!

Mr0grog commented Jun 3, 2016

Uh oh!

Mr0grog Jun 22, 2016

Uh oh!

jedmccaleb Jun 22, 2016

Uh oh!

Mr0grog commented Jun 22, 2016 •

edited

Loading

Uh oh!

irisli Jun 27, 2016

Uh oh!

Mr0grog Jun 27, 2016

Uh oh!

irisli Jun 27, 2016

Uh oh!

irisli Jun 27, 2016

Uh oh!

Mr0grog commented Jun 28, 2016

Uh oh!

Mr0grog commented Jun 28, 2016

Uh oh!

irisli commented Jun 29, 2016 •

edited

Loading

Uh oh!

irisli commented Jun 29, 2016

Uh oh!

Uh oh!

WIP: Rewriting the get started flow #136

WIP: Rewriting the get started flow #136

Uh oh!

Conversation

Mr0grog commented Jun 1, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bartekn commented Jun 3, 2016

Uh oh!

Mr0grog commented Jun 3, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mr0grog commented Jun 22, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mr0grog commented Jun 28, 2016

Uh oh!

Mr0grog commented Jun 28, 2016

Uh oh!

irisli commented Jun 29, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

irisli commented Jun 29, 2016

Uh oh!

Uh oh!

Mr0grog commented Jun 22, 2016 •

edited

Loading

irisli commented Jun 29, 2016 •

edited

Loading