https://developer.algorand.org/docs/features/asc1/sdks/#accessing-teal-program-from-sdks

Once all pages are written, we need to go back through and make sure everything is linked correctly and intuitively.

"Looking at participation, I realized that https://developer.algorand.org/docs/run-a-node/participate/online/ does not explicitely show how to sign the transactions and broadcast it. I think it would be best to add a section before “Check that the node is participating” -> “Sign and Broadcast the Transaction” maybe no code for sign, but some text and link to the relevant part"

Example Walthrough of a TEAL Program
https://developer.algorand.org/docs/features/asc1/teal_overview/

Link to Node Types on https://developer.algorand.org/docs/reference/node/config/ is https://developer.algorand.org/docs/network-participation/run-a-node/types/ and should be https://developer.algorand.org/docs/run-a-node/setup/types/

On pages with code, the first paragraph somewhere, let the reader know that the completed solution is at the bottom of the post.

Change to virtually all Java examples that build transactions to the builder format like:

    Transaction tx = Transaction.AssetCreateTransactionBuilder()
            .sender(sender)
            .fee(10)
            .firstValid(322575)
            .lastValid(323575)
            .genesisHash(gh)
            .assetTotal(100)
            .assetDecimals(numDecimal)
            .assetUnitName("tst")
            .assetName("testcoin")
            .url("website")
            .metadataHashUTF8(metadataHash)
            .manager(manager)
            .reserve(reserve)
            .freeze(freeze)
            .clawback(clawback)
            .build();

Currently using tag to indicate that the preceding text needs to carry the placeholder variable style as shown here: https://developers.google.com/style/code-in-text

Once style is implemented, we should make sure it looks okay in all languages.

https://developer.algorand.org/docs/run-a-node/setup/install/

refers to this link:
https://developer.algorand.org/docs/reference-docs/node_files/#phonebookjson

and should be

https://developer.algorand.org/docs/reference/node/artifacts/

Create docs for kmd commands similar to the way goal was updated.

Attempting to retrieve an asset by index value that does not exist results in a 404 - but the documentation does not capture this possibility.

`root@7ff87f1bb76a:/opt/algorand/node# curl -v -H "X-Algo-API-Token: $(cat ./data/algod.token)" http://127.0.0.1:4001/v1/asset/15

• Trying 127.0.0.1...
• TCP_NODELAY set
• Connected to 127.0.0.1 (127.0.0.1) port 4001 (#0)

GET /v1/asset/15 HTTP/1.1
Host: 127.0.0.1:4001
User-Agent: curl/7.58.0
Accept: /
X-Algo-API-Token: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

< HTTP/1.1 404 Not Found
< Access-Control-Allow-Headers: X-Algo-API-Token, Content-Type
< Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
< Access-Control-Allow-Origin: *
< Date: Thu, 12 Mar 2020 14:41:46 GMT
< Content-Length: 48
< Content-Type: text/plain; charset=utf-8
<

• Connection #0 to host 127.0.0.1 left intact
  failed to retrieve asset creator from the ledgerroot@7ff87f1bb76a:/opt/algorand/node# `

https://forum.algorand.org/t/participation-key-docs-need-updated/1546

Change side nav formatting - Part 1

Add title: <title> tag lines to each of the .pages files and at the tops of the .md files to do two things:

1. Make related side nav items all lowercase.
2. Specify full command on side nav, instead of just current layer.

Here is an example of what the result should look like:

Alphabetize side nav

Alphabetize all sub commands, except for the top layer command. I.e. order commands via the .pages files.

Various clean-up

Remove auto-generated cobra line at bottom of all docs.

Add "Edit page" buttons to each doc page that link back to the Github markdown file so users can easily edit.

Feature Guides section

Review for technical accuracy in explanations. Also review code for correctness and consistency.

Some of these are written as required when they should be optional.

Pages under docs/networks/* will include latest protocol version, build, etc. This needs to be hooked into build pipeline to update accurately.

We need a user flow for service providers who are looking to integrate with Algorand. This may be a separate section in the docs side nav with guides for specific types of service providers. e.g. "As a wallet provider..", "As a block explorer..."

We have a lot of technical terms sprinkled throughout our documentation. To make it easier for readers with various levels of knowledge about Algorand, let's create a glossary that can provide a quick reference for terms like "Multi Transfer Transaction". Consider including an object model to show how things are connected together. Blocks, transactions, Accounts, etc.

See ASA page. Add full code links under each snippet to signal where the context is.

For code snippets that are part of a larger function (and therefore indented), remove the indent for the snippet portion. Check that this is consistent and confirm that this looks best (as opposed to just showing the snippet indented).

The full code example at the bottom of the relevant page will include the snippet correctly indented.

Network Participation Section

Describe the error

On https://developer.algorand.org/docs/run-a-node/operations/switch_networks/, it may look like switching to BetaNet just require to switch the generis block and the config.json. But it also requires to use the beta version of algod.

Link to the page or line

Full page: https://developer.algorand.org/docs/run-a-node/operations/switch_networks/

Optional - The recommended fix if you have one

Explain that BetaNet also requires to use the Beta software and how this can be achieved.

"The goal documentation (goal clerk send -h) says
--noteb64 string Note (URL-base64 encoded)
but this python code (as well as my bash script) returns a standard base64, not URL-base64.

For example you can check that encoding the number 12345678012 yields 'AAAAAt/cGLw=' and encoding 1234567801234 yilds 'AR9x+amS'. This does not seem to be a problem, I was able to send transactions with this note field to the network with no issues, so I guess it's the documentation that needs to change."

Getting Started Section

The current state

DevNet is never mentioned in the documentation, which might be confusing.

See:

• https://forum.algorand.org/t/what-is-devnet-v1-0/1378
• https://forum.algorand.org/t/betanet-requires-a-reset-of-previously-running-nodes/1606/23

The proposed state

Adding a column to https://developer.algorand.org/docs/build-apps/setup/#choosing-a-network for DevNet and/or some text in the paragraph above

The endpoint GET /v1/transaction/{txid} returns a 500 as text/plain when a transaction is submitted where the id is well formed (borrowed from the alternate ledger, MainNet in this case) and the indexer is on. Documentation states it should return a 404.

There may be some alternate scenario at work here?

algo@server:~$ curl -v -H "X-Algo-API-Token: $(cat ./data/algod.token)" http://127.0.0.1:48081/v1/transaction/JK4DZ4OWTE2HLUGJ64V6ZHTZZ5MCGLAR3W4CXBNRMOM2JDXBBV7A

• Trying 127.0.0.1...
• TCP_NODELAY set
• Connected to 127.0.0.1 (127.0.0.1) port 48081 (#0)

GET /v1/transaction/JK4DZ4OWTE2HLUGJ64V6ZHTZZ5MCGLAR3W4CXBNRMOM2JDXBBV7A HTTP/1.1
Host: 127.0.0.1:48081
User-Agent: curl/7.58.0
Accept: /
X-Algo-API-Token: somevalidstringhere

< HTTP/1.1 500 Internal Server Error
< Access-Control-Allow-Headers: X-Algo-API-Token, Content-Type
< Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
< Access-Control-Allow-Origin: *
< Date: Fri, 13 Mar 2020 12:52:59 GMT
< Content-Length: 46
< Content-Type: text/plain; charset=utf-8
<

• Connection #0 to host 127.0.0.1 left intact
  failed retrieving information from the indexer

Investigate one-click up and running methods. Workspace Setup is still too heavy. Can we integrate address and token in-browser or integration with API service partner, etc.

Make docs public and open source.

Is your addition related to a problem? Please describe.

For more complex workflows, it is useful to know how objects such as transactions are encoded/decoded.

See:

• https://forum.algorand.org/t/method-to-serialize-a-json-to-transaction/1259
• https://forum.algorand.org/t/javascript-frontend-communicating-with-python-backend/1728/2

Describe the solution you'd like

Adding an advanced topic / reference doc about encoding/decoding objects in Algorand.

This would include:

• explaining that transaction files are concatenations of msgpack-encoded transactions, with a customized version of msgpack that provides canonical encoding and omits empty fields
• explaining that addresses do not have the base32 checksum and providing a way to convert checksumed addresses from/to non-checksumed ones:

$ python3 -c "import algosdk; import base64; print(algosdk.encoding.encode_address(base64.b32decode('YESQSK5RT7WXWKCRTQN3PJZSZSMV63VDVRJAB5EBDYLXCJH5ZGTQ====')))"
YESQSK5RT7WXWKCRTQN3PJZSZSMV63VDVRJAB5EBDYLXCJH5ZGTQDBRKDE

$ python3 -c "import algosdk; import base64; print(base64.b32encode(algosdk.encoding.decode_address('YESQSK5RT7WXWKCRTQN3PJZSZSMV63VDVRJAB5EBDYLXCJH5ZGTQDBRKDE')).decode())"
YESQSK5RT7WXWKCRTQN3PJZSZSMV63VDVRJAB5EBDYLXCJH5ZGTQ====

• providing some background information about msgpack
• explaining that this also applies to logic sig
• showing how to encode/decode manually transactions using msgpacktool and the various SDK
• explaining that this allows to pass transactions around more easily
• explaining the difference between goal clerk inspect and msgpacktool
• explaining how to use msgpack to encode objects in note field

This feedback is in a Google doc.

Using the Python SDK I had the need to use the CloseRemainderTo field in a Payment Transaction. According to the table in Dev Docs, the codec to be used for this field is "close". Compiling the Python code with the "close" field results in an error.

Payment Transaction reference

The correct codec for the Python SDK is "close_remainder_to". Maybe could be useful to integrate the SDKs field in the Transaction reference too.

Make sure we reference the same types of variables the same way throughout examples for the same language. Keep naming consistent across languages too inasmuch as the style for that language allows.

There are a number of other useful tools that get built with the go-algorand project that can be useful to the developer community that aren't described in the same detail as goal, kmd, and algokey, for example algotmpl, dsign, dispenser, etc.

Consider additional content for each, if they are useful and have a shelf life.

Shai: "...the links at the top level are confusing. In particular, clicking on a category such as "Explore Features" or "Reference Docs" links to the first subtopic inside these categories, with no easy way of getting to the other subtopics, or even a hint that they exist. (For example clicking "Explore Features" brings me to "accounts", with seemingly no way to get to "Transactions", "Assets", etc.). The only way that I found to get to these other subtopics is the menu on the left.

I think that either the top-level links should point to lists of all the subtopics, or at least the table-of-content showing on the right in the subtopics should include all the subtopics (rather than just the current one), "

https://developer.algorand.org/docs/run-a-node/setup/install/

This is confusing if you just want the binaries. We need to clarify this language and also include a separate section to just include the binaries.

Add clarity for app developers around use of indexer aligned with indexer v2 launch. Currently documentation is in node configuration section. We need to surface implications of this clearly.

Is your addition related to a problem? Please describe.
A clear and concise description of what the problem is. What confusion does it cause? How does it affect developers?

• Developers need to understand how fees work to understand a) what infrastructure they need to (or don't need to) create when submitting transactions and b) to model out anticipated costs for their business.

Describe the solution you'd like
A clear and concise description of what you want to happen. Which section needs to be added/modified? What should it include?

• A new section "Explore Features". How fees are calculated, congested network scenarios, how fees prioritize transactions, etc

Describe alternatives you've considered
A clear and concise description of any alternative solutions you've considered.

• None.

Additional context
Add any other context or screenshots about the documentation request here.

Requires new icon from Hipo.

Is your addition related to a problem? Please describe.
A clear and concise description of what the problem is. What confusion does it cause? How does it affect developers?

The REST API https://developer.algorand.org/docs/reference/rest-apis/algod/ uses many types. For some such as date or string (byte) or boolean it may be difficult to know what the correct encoding is.

Describe the solution you'd like
A clear and concise description of what you want to happen. Which section needs to be added/modified? What should it include?

Two proposed solutions (which can be combined):

• Provide a page describing the encoding formats of the various types.
• Have a tooltip displaying the format when clicking on a given type

In the documents here - https://developer.algorand.org/docs/reference/rest-apis/algod/ - all endpoints state that they have an output Content-Type in the format application/json.

Above the statement concerning the output, is typically a table of different response codes, example -

Confusion arises between the schema defined in the table, particularly for an error, and the expected Content-Type of the message and the different SDK's error handling.

For example, the PureStake API had the result of a 400 bad transaction returned as application/json content type although the actual output is not JSON but a string TransactionPool.Remember: txn dead: round 5395354 outside of 5153790--5154790.

This can cause parsing errors in the JS SDK library when it expects a JSON object. We switched it to produce 'text/plain' but are not certain if that was correct.

Ideally everything would return as JSON and the SDKs could properly parse out errors like the above. If not feasible, some clarification in the documentation about the expected Content-Type for the different response codes.

Is your addition related to a problem? Please describe.

To check that a transaction has been confirmed, the recommended way is to use the REST API call https://developer.algorand.org/docs/reference/rest-apis/algod/#get-v1accountaddrtransactionspending

This raises the following questions:

1. If I submit a transaction on node A, can I wait for confirmation on node B? Knowing this is useful when you use a load-balancer in front of multiple nodes.
2. How long after submitting the transaction will it stay in the pending transactions pool? Knowing this is useful when you want to make many transactions at once and only check later whether they have actually been committed.

Describe the solution you'd like

Add some documentation about the pending pool, including answers to the above questions.

Describe alternatives you've considered
A clear and concise description of any alternative solutions you've considered.

Additional context
Add any other context or screenshots about the documentation request here.

Adapt this page and include more code how-tos. https://www.algorand.com/resources/blog/rewards-technical-overview

Add to "Explore Features" as separate section called "Rewards"

For the Java SDK example, to send an asset the text reads, in part We set the assetCloseTo to null so we do not close the asset out - and the code reflects that on the method invocation

tx = Transaction.createAssetTransferTransaction(acct1.getAddress(), acct3.getAddress(), assetCloseTo, assetAmount, BigInteger.valueOf( 1000 ), cp.firstRound, cp.lastRound, null, cp.genID, cp.genHash, assetID);

However this results in an error today - .algorand.algosdk.algod.client.ApiException: Bad Request : signature validation failed.

We swapped out the null with an empty address and it worked, new Address().

Text found here - https://developer.algorand.org/docs/features/asa/

Until security library is fixed