Standardize how we display terminal/bash code blocks

[wileyj]

We have prior art where we've typically used a code block like this to show terminal or bash commands:

$ echo "test string"

However, Akirtovskis mentioned in stacks-network/stacks-blockchain-docker#39 that it would make things easier to remove the $ from terminal/bash, like this:

echo "test string"

Personally, I agree with this approach - the only reason I had added the $ is because of prior docs/readme's that we've published where the $ exists.

To keep this issue easily scoped, we should go through existing docs here and remove the $ or any other shell/terminal identifier ( % is another example).
Later, it would be nice to work on a style-guide that we use here with the goal of standardizing how we create docs with the goal of making them easy and accessible. ( @pgray-hiro )

[Akirtovskis]

Happy to jump in and help with PRs that remove $ and % in docs if some sort of list or scope of repositories is provided.

[pgray-hiro]

@Akirtovskis I would certainly love the assistance - I want to just put it to our dev team to make sure this is how we want to standardize, once we've sorted that out I can provide a resource list

[pgray-hiro]

@Akirtovskis After internal discussion and discussion with the community, we've settled on not including the $ or % terminal prompt in any docs or READMEs. There is one exception to this rule, if the code block is showing the command and the example output of the command for example:

$ stx balance SP2JM9EMVHHRHWHW82CD9XQMTYTM8BG2RWG58WQVB
{
  "balance": "18588980982",
  "locked": "0",
  "unlock_height": 0,
  "nonce": 1609
}

In the above case it would be acceptable to leave as is, or as a best practice it would be preferred to split the example command and the output with some expository text between them.

As far as doc updates go, this repo would be the primary target, but we would appreciate additional PRs on READMEs in any repo in the blockstack organization. Let me know if this is something you can take on.

[Akirtovskis]

@pgray-hiro I am definitely up for doing this!

[Akirtovskis]

Creating a list of repos I have gone through here and created PRs:

This covers all of the most recently modified ( 1y or newer repos ).

Let me know if there's a need to look into older ones as well.

• https://github.com/blockstack/stacks-blockchain
  PR docs: remove redundant $ from terminal commands stacks-core#2700

• https://github.com/blockstack/stacks-local-dev
  PR docs: remove redundant $ from terminal command stacks-blockchain-docker#44

• https://github.com/blockstack/subdomain-registrar
  PR docs: remove redundant $ in terminal commands subdomain-registrar#62

• https://github.com/blockstack/blockstack-search-indexer
  PR docs: removing the unnecessary $ from terminal commands. stacks-archive/blockstack-search-indexer#10

• https://github.com/blockstack/zone-file-js/
  PR docs: removing the unnecessary $ from terminal commands. zone-file-js#8

• https://github.com/blockstack/blockstack-browser
  PR docs: removing the unnecessary $ from terminal commands. stacks-archive/blockstack-browser#2073

• https://github.com/blockstack/gh-action-testing
  PR docs: removing the unnecessary $ from terminal commands. hirosystems/gh-action-testing#2

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically closed. Please reopen if needed.