Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Incorporating a few suggestions to the new docs. #28

Merged
merged 4 commits into from
Sep 1, 2022

Conversation

Shaptic
Copy link
Contributor

@Shaptic Shaptic commented Sep 1, 2022

This includes a few of my suggestions from Slack, but doesn't include these:

  • It's a little off-putting to see

The lumen is the only token that doesn’t require an issuer or trustline, and it pays all transaction fees and covers minimum balances on the network.
on the XLM page before introducing what issuer and trustlines are :thinking_face: but I'm not sure how to do that better.

  • In the List of Operations, some have errors in a tabular form and some don't. Should those be consistent?
  • Can we get MathJax support?

Since these are a little more opinionated and/or involved, so I'll leave those to @briwylde08.

@Shaptic Shaptic requested review from briwylde08 and kalepail and removed request for briwylde08 September 1, 2022 18:23
@stellar-jenkins
Copy link

@kalepail
Copy link
Contributor

kalepail commented Sep 1, 2022

Docusaurus supports https://katex.org/ and I've added that to this branch

@stellar-jenkins
Copy link

@kalepail
Copy link
Contributor

kalepail commented Sep 1, 2022

@briwylde08

  • 1. It's a little off-putting to see

    The lumen is the only token that doesn’t require an issuer or trustline, and it pays all transaction fees and covers minimum balances on the network.

    on the XLM page before introducing what issuer and trustlines are 🤔 but I'm not sure how to do that better.

  • 2. In the List of Operations, some have errors in a tabular form and some don't. Should those be consistent?

  • 3. On the trustlines page (link), it states

    Learn more here: Claimable Balances Encyclopedia Entry

    but something like "You can learn more from the claimable balances encyclopedia entry." flows better imo. (Btw love the rename of glossary -> encyclopedia.)

  • 4. Quoting "burn" here might make this sentence flow better

    To delete, or burn, an asset, you must send it back to the account that issued it.

@tyvdh

  • 1. Can we get MathJax support? Seeing e.g. The largest amount unit possible is ((2^63)-1)/(10^7) is not very eye-pleasing.

@kalepail
Copy link
Contributor

kalepail commented Sep 1, 2022

@briwylde08
Personally

  1. I think this is worth looking into a bit more to see if you agree and if there's anything to be done here
  2. I believe this was due to a lack of documentation on the SDK side but opting to prefer API docs over rehashing existing docs. Once we convert over to the OpenAPI spec this will become consistent. Is that true?
  3. I don't have a strong opinion here other than if we change it in one place it needs to be changed everywhere and this format is used in a lot of places. My gut says just leave it. I tend to prefer canonical style links vs conversational in my docs.
  4. I agree on the quotes.

@kalepail
Copy link
Contributor

kalepail commented Sep 1, 2022

@Shaptic Nice!
Screen Shot 2022-09-01 at 3 13 30 PM

@Shaptic
Copy link
Contributor Author

Shaptic commented Sep 1, 2022

@tyvdh thinking about this more, I don't see much math besides the bit I found lol. Do you think the JavaScript cost (e.g. the big file to download + execute) on every page (is it every page? or only pages where you use $ <math> $ in the source?) is worth the handful of instances where we use a bit of math that can be improved w/ HTML (e.g. <sup> like I did before) or Unicode characters?

@kalepail
Copy link
Contributor

kalepail commented Sep 1, 2022

I mean it'll be cached and progressively loaded so it's not a big lift

@stellar-jenkins
Copy link

@Shaptic
Copy link
Contributor Author

Shaptic commented Sep 1, 2022

Re (2), converting to OpenAPI will definitely help a lot with consistency, but I think adding thorough details like these per-operation error messages is a "phase 2" extension to the spec that will need more work to write and possibly integrate. I just wanted to call it out because we have error and parameter tables for all of the operations in the existing list of operation docs. It may be better to keep them as-is, then replace them with links like done here when the API docs are confirmed to have the same info and level of detail?

@briwylde08
Copy link
Contributor

  1. Makes sense. I think our options here are to link to the sections on trustlines and issuers below this introduction. Or we can move the entire Lumens section below the Stellar Data Structures section. I'm okay either way- @tyvdh any opinions about where Lumens is in the overall F&C section?

  2. Ideally we'd have consistency across all operations, the reason there are some tables and some links for parameters/errors is because, yes, some of the documentation in the API docs was missing. I liked the idea of not having the tables just because it's so much cleaner.

  3. Most of the links in the new docs are not conversational so this would have to be changed in a lot of places. I dunno, I think this is probably a preference thing? My idea is that... putting too many links conversationally throughout the docs makes people click away too much. I want them to get all the way through the paragraph/section and then decide if they want more information. But, again, probably just a preference thing.

  4. Fine by me

@kalepail kalepail force-pushed the bri-content-suggestions branch from 3424332 to 4eea30b Compare September 1, 2022 20:57
@kalepail kalepail merged commit e1a83fb into bri-content Sep 1, 2022
@kalepail kalepail deleted the bri-content-suggestions branch September 1, 2022 20:58
@stellar-jenkins
Copy link

3 similar comments
@stellar-jenkins
Copy link

@stellar-jenkins
Copy link

@stellar-jenkins
Copy link

kalepail added a commit that referenced this pull request Sep 1, 2022
* update some docs links

* update welcome page

* added fundamentals and concepts and deleted old start directory

* new tools and sdks docs

* new glossary

* glossary -> encyclopedia

* updated encyclopedia

* Added code blocks (#10)

* Added code blocks

Please look at why it won't tab out the code blocks!

* added json5 and missing python library

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* Added code blocks (#13)

* Added missing information to operations (#11)

* Added missing information to operations

Including: LPs, clawbacks, claimable balances

* Update list-of-operations.mdx

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* Added code blocks (#14)

* delete some dupe content

* Added code blocks (#15)

* Added code blocks

Please look at why it won't tab out the code blocks!

* added json5 and missing python library

* Added code blocks

* spaces matter apparently

* nvm

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* Added code blocks (#16)

* Added code blocks & missing link (#17)

* Added code block (#20)

* Added code blocks, edited some content (#22)

Removed Example 5 (to be added later)

* spacing tweaks

* Added code blocks (#21)

* omit CodeExample block on non code blocks

* Added code blocks (#18)

* Added code blocks

* encyclopedia

* space tweak

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* Added code blocks (#19)

* Added code blocks

* removed some spaces

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* missed a couple imports

* glossary -> encyclopedia

* lint

* format mdx

* no cache on the make

* case fix step 1

* case fix step 2

* fixed a link

* added another link from the hash

* Update sponsored-reserves.mdx

* Glossary-Encyclopedia network passphrases

* Anchoring assets-xborder payments links

* Update setting-up-test-server.mdx

* Update withdraw-anchored-assets.mdx

* Update custom-assets.mdx

* Update first-deposit.mdx

* Update project-setup.mdx

* Update setup-custodial-account.mdx

* Update anatomy-of-an-asset.mdx

* Update control-asset-access.mdx

* Issuing assets - control asset access

* Issuing assets - publishing asset info

* run core node - configuring links

* Update monitoring.mdx

* Tutorials - create account

* Update setting-up-production-server.mdx

* tutorials - follow received payments links

* tutorials - send and receive payments links

* run a core node - index links

* Added community (#25)

Add and update community channels

* link tweaks

* couple more tweaks

* glossary links

* issuing assets - anatomy of an asset link

* encyclopedia - claimable balance links

* encyclopedia - error handling links

* encyclopedia - fee bump links

* Update fees-surge-pricing-fee-strategies.mdx

* Update ledger-headers.mdx

* encyclopedia - flags links

* Update claimable-balances.mdx

* Update error-handling.mdx

* Update fee-bump-transactions.mdx

* encyclopedia - liquidity on stellar links

* encyclopedia - memos links

* encyclopedia - path payments links

* encyclopedia - pooled accounts links

* encyclopedia - signatures and multisig links

* encyclopedia - sponsored reserves links

* fundamentals & concepts - data strctr - accts links

* f&c - data structures - assets links

* f&c - data structures - ledgers links

* f&c - data structures - operations & transactions links

* f&c - operations links

* f&c - lumens links

* f&c - testnet&pubnet links

* updated link in pooled accounts

* added sdk library link

* minor link tweaks

* minor styling update for h4s

* oops

* updates

* Added run a core node link

* Remove link to Lumens, not relevant anymore

* Fixed a couple of links (#26)

Removed .mdx from two links to testnet/pubnet section

* Removed unnecessary )

* Added claimable balances link

* fix issuing assets link

* fixed sep1 link

* fixed links to info file and issuing assets

* attempt at the first 302

* move nginx conf stuff around

* Update redirects.conf

* Update redirects.conf

* Update nginx.conf

* Update nginx.conf

* try that?

* Update redirects.conf

* added SCP link & run api server link

* Update redirects.conf

* no need for this block

* Updating footer (#27)

* Updating footer

Change developers-community and add community links
All tools to link to dev docs tools page 
Remove get started from resources

* update footer content

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* noop

* Changed links to tables for parameters&errors

* Incorporating a few suggestions to the new docs. (#28)

* Small improvements to link naming and math rendering

* add KaTeX

* Change math to use TeX

* don't update this

Co-authored-by: Tyler van der Hoeven <hi@tyvdh.com>

* tiny lint tweaks

* Update list-of-operations.mdx

* updated table links

* Updating ledgerkey definition (#29)

* move Lumens under the Stellar Data Structures directory

Co-authored-by: Bri <92327786+briwylde08@users.noreply.github.com>
Co-authored-by: George <Shaptic@users.noreply.github.com>
ElliotFriend pushed a commit that referenced this pull request Mar 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants