Token/Custom Assets Creation Documentation

Question

OK, I have reviewed both of the Stellar.org created documents on creating Custom Assets/Tokens, then I looked at two third party documents. The third party documents are much much better than anything Stellar has created itself.

Here are the Stellar documents >

https://www.stellar.org/blog/tokens-on-stellar/ https://www.stellar.org/developers/guides/walkthroughs/custom-assets.html

Here are the third party documents>

https://www.lumenauts.com/guides/how-to-issue-a-token-or-ico-on-stellar https://medium.com/@brenn.a.hill/how-to-make-a-custom-token-on-stellar-ae5296512a2e

Here is why. The Stellar documents have links to generic function descriptions that provide me no insight to the parameters needed for all steps. The linked pages don't have all the information needed to complete the setup nor do they give someone a clear understanding of why each parameter and step are required other than a high-level description of what the step is.

The only problem with the third party docs is that at least one of them do not make it clear how to proceed when moving from the test network token creation to the public while creating tokens. None of the documents provide a clear understanding of the fees and costs associated with standing up a public token/custom assets.

Ok now the question, why is this the case if you agree? If you disagree then please troll me until the cows come home for making the wrong assumptions about the existence of clear guidance on Stellar's site. However, afterwards please point me to that document.

Answer 1

They have different target groups. The one is an additional guide for developers who have to learn all the concepts anyways and know how to find and read API docs. The others are step-by-step single purpose quickstart tutorials for anyone with the main goal to demonstrate ease of asset creation with minimal effort. They show you how to create an asset in 5 minutes and give you an immediate sense of achievement but they barely teach you anything. Both tutorials leave out stellar.toml for example, the first tutorial locks the issuer account without further explanation, the second one even uses wrong terms like transaction type where it should be operation.

Just walk through all "Concepts" at https://www.stellar.org/developers/guides/ especially the transactions and operations. It will take time and you might not understand everything at a first glance but as soon as you get a basic understanding you won't need step-by-step tutorials any more.

Answer 2

The documentation is not good. Its not just about writing to different audiences. It needs to be written correctly as a start, then consider writing to different audiences. This is just one of many examples I have seen, but see below where there are typos when using StellarBase vs StellarSdk. The class and function call uses StellarSdk and the rest of the code uses StellarBase. Highly confusing for someone new to Stellar and just trying to learn this stuff.

StellarSdk.Network.useTestNetwork();
// StellarBase.Network.usePublicNetwork(); if this transaction is for the public network
// Create an Account object from an address and sequence number.
var account=new StellarBase.Account("GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD","2319149195853854");

var transaction = new StellarBase.TransactionBuilder(account, {
      fee: StellarBase.BASE_FEE
    })
        // add a payment operation to the transaction
        .addOperation(StellarBase.Operation.payment({
                destination: "GASOCNHNNLYFNMDJYQ3XFMI7BYHIOCFW3GJEOWRPEGK2TDPGTG2E5EDW",
                asset: StellarBase.Asset.native(),
                amount: "100.50"  // 100.50 XLM
            }))
        // add a set options operation to the transaction
        .addOperation(StellarBase.Operation.setOptions({
                signer: {
                    ed25519PublicKey: secondAccountAddress,
                    weight: 1
                }
            }))
        // mark this transaction as valid only for the next 30 seconds
        .setTimeout(30)
        .build();

Next, even with the fix, this example does not work. It needs way more in finishing touches like a call to require the stellar-sdk nodejs package or some guidance if it is not nodejs regarding how to include for javascript clients.

Even if I fix ALL of that guess what? Error message below:

                    ed25519PublicKey: secondAccountAddress,
                                      ^

ReferenceError: secondAccountAddress is not defined
    at Object.<anonymous> (/var/www/stellarjs/ASSET_CREATION/TESTINGSHIT/transaction.js:19:39)
    at Module._compile (module.js:653:30)
    at Object.Module._extensions..js (module.js:664:10)
    at Module.load (module.js:566:32)
    at tryModuleLoad (module.js:506:12)
    at Function.Module._load (module.js:498:3)
    at Function.Module.runMain (module.js:694:10)
    at startup (bootstrap_node.js:204:16)
    at bootstrap_node.js:625:3

Not good for newbies trying to learn this stuff and follow your guidance to test things as they go. If this code was not meant to test then it should not be portrayed in your docs as something that can be followed that works. It doesn't. That has nothing to do with levels of individuals looking at the docs. That is just a basic documentation requirement.

Again, I strongly suggest a major review and edit of your documentation BEFORE your road map dictates.

Answer 3

By the way. Here is what I call good documentation. The author gets to the point, describes what the title says and it works from start to finish. How can I list and sell Stellar based Tokens (not XLM)?