docs: improve documentation (taikoxyz#8556)

CONTRIBUTING.md

@@ -1,110 +1,62 @@
-# Contributing guide
+# Taiko contributing guide
 
-This contributing guide is divided into the following sections:
+**Table of contents:**
 
-1. [Make a contribution](#make-a-contribution)
-2. [Claim a GitPOAP](#claim-a-gitpoap)
-3. [Git standards](#git-standards)
-4. [Documentation style guide](#documentation-style-guide)
+- [Make a contribution](#make-a-contribution)
+- [Claim a Taiko Contributor GitPOAP](#claim-a-taiko-contributor-gitpoap)
+- [Coding standards](#coding-standards)
+- [Documentation standards](#documentation-standards)
 
 # Make a contribution
 
-We use [GitHub issues](https://github.com/taikoxyz/taiko-mono/issues) to track work. We use [GitHub discussions](https://github.com/taikoxyz/taiko-mono/discussions) to ask questions and talk about ideas.
+Here are some ways you can contribute:
 
-## Opening a new issue
+- Open a new issue [here](https://github.com/taikoxyz/taiko-mono/issues).
+- Work on an existing issue (check out the [good first issues list](https://github.com/taikoxyz/taiko-mono/labels/good%20first%20issue)).
+- Ask questions and participate in [discussions](https://github.com/taikoxyz/taiko-mono/discussions).
 
-If you are opening a new issue, try to be descriptive as possible. Also please check if an existing issue already exists for it already.
+> Check out the [coding standards](#coding-standards) and [documentation standards](#documentation-standards) before you start working on a pull request.
 
-## Working on an issue
+# Claim a Taiko Contributor GitPOAP
 
-If you are looking for a good issue to start with, look for issues tagged with [good first issue](https://github.com/taikoxyz/taiko-mono/labels/good%20first%20issue). Once you've found an issue to work on, you can assign it to yourself on GitHub and/or leave a comment that you're picking it up. Take a look at our [git standards](#git-standards).
+A Taiko Contributor GitPOAP is rewarded to anyone that merges in a pull request to one of Taiko's GitHub repositories (for example: [2023 Taiko Contributor GitPOAP](https://www.gitpoap.io/gp/893)).
 
-## Ask questions and start discussions
+After your pull request is merged, a bot will automatically leave a comment with instructions to receive your GitPOAP. You only receive a Taiko Contributor GitPOAP for the first pull request you merge in a given year.
 
-You can participate in questions and discussions under our [GitHub discussions](https://github.com/taikoxyz/taiko-mono/discussions).
+# Coding standards
 
-# Claim a GitPOAP
+### Pull requests
 
-We are rewarding community contributions with a GitPOAP. This guide explains the requirements to claim a GitPOAP.
+Specify the scope of your change with a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) in the PR title (for example, `feat(scope): description of feature`). This will be squashed and merged into the `main` branch.
 
-## XXXX Taiko Contributor GitPOAP
+### Source code comments
 
-The XXXX Taiko Contributor GitPOAP is intended for anyone who makes a meaningful contribution to Taiko during the year XXXX. You can only earn this in the following ways:
+Follow the [NatSpec format](https://docs.soliditylang.org/en/latest/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards:
 
-- Receive an accepted answer under [GitHub Discussions](https://github.com/taikoxyz/taiko-mono/discussions)
-- Merge in a change to one of [our GitHub repos](https://github.com/taikoxyz)
+- Choose `/** */` over `///` for multi-line NatSpec comments to save column space.
+- Omit the usage of `@notice` and let the compiler automatically pick it up to save column space.
+  - For example: `/** @notice This is a notice */` becomes `/** This is a notice */`.
 
-## How do I receive my GitPOAP?
+# Documentation standards
 
-There are two ways to receive a GitPOAP:
+Use the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) as a base point of reference.
 
-- If you merged in a pull request, the gitpoap-bot should have left you a comment to receive your GitPOAP like so:
-  ![](/assets/images/2022-12-14-09-30-37.png)
-- If you made another contribution which fits the requirements of the GitPOAP, please ping the team on Discord so we can issue a GitPOAP manually.
+### Philosophy
 
-# Git standards
-
-## Creating commits
-
-Try to specify the scope of your change via a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) (eg. `enhance(docs): improve some section`) or specifying the scope in brackets (eg. `[docs] improve some section`).
-
-## Submitting a PR
-
-Please make sure to use a conventional commit in your PR title (eg. `feat(scope): description of feature`). This will be squashed and merged into the `main` branch.
-
-## GitHub Actions
-
-Each commit will automatically trigger the GitHub Actions to run. If any commit message in your push or the HEAD commit of your PR contains the strings [skip ci], [ci skip], [no ci], [skip actions], or [actions skip] workflows triggered on the push or pull_request events will be skipped.
-
-# Documentation style guide
-
-Many standards are adopted from [Google dev docs highlights](https://developers.google.com/style/highlights).
-
-## Philosophy
-
-- Create the [minimum viable documentation](https://google.github.io/styleguide/docguide/best_practices.html#minimum-viable-documentation).
+- Create the minimum viable documentation.
 - Don't repeat yourself, use links to existing documentation or inherit it.
-- Keep documentation close to what it's describing, also called high cohesion (eg. describing a smart contract should be documented as comments in the source code).
+- Keep documentation close to what it's describing (for example, in the source code).
 
-## Document types
+### Document types
 
 Group documentation under one of the four categories (adopted from [Diátaxis](https://diataxis.fr/)):
 
-- Tutorials
-- Guides
+- How to
 - Concepts
+- Tutorials
 - Reference
 
-## Tone and content
-
-- [Use descriptive link text](https://developers.google.com/style/link-text).
-- [Write accessibly](https://developers.google.com/style/accessibility).
-- [Write for a global audience](https://developers.google.com/style/translation).
-
-## Language and grammar
-
-- [Use second person](https://developers.google.com/style/person): "you" rather than "we".
-- [Use active voice](https://developers.google.com/style/voice): make clear who's performing the action.
-- [Put conditional clauses before instructions](https://developers.google.com/style/clause-order), not after.
-
-## Formatting, punctuation, and organization
-
-- [Use sentence case](https://developers.google.com/style/capitalization) for document titles and section headings.
-- [Use numbered lists](https://developers.google.com/style/lists#types-of-lists) for sequences.
-- [Use bulleted lists](https://developers.google.com/style/lists#types-of-lists) for most other lists.
-- [Use description lists](https://developers.google.com/style/lists#types-of-lists) for pairs of related pieces of data.
-- [Use serial commas](https://developers.google.com/style/commas).
-- [Use unambiguous date formatting](https://developers.google.com/style/dates-times).
-
-## Source code comments
-
-Follow the [NatSpec format](https://docs.soliditylang.org/en/v0.8.16/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards:
-
-- Choose `/** */` over `///` for multi-line NatSpec comments, to save column space
-- Omit the usage of `@notice`, this will be automatically picked up so it will save column space and improve readability
-- Take advantage of inheritance for docs (such as documenting the interface), if you need to specify inherited docs use `@inheritdoc`
-
-## Images
+### Images
 
 - Use SVG files or crushed PNG images.
 - Provide alt text.

packages/website/docs/alpha-1-testnet/configure-wallet.mdx

@@ -8,7 +8,7 @@ import AddEthereumChainButton from "../../src/components/AddEthereumChainButton"
 
 ## Automatically add networks
 
-Use the buttons below to add Ethereum A1 and Taiko A1 to any wallet that supports `wallet_addEthereumChain` (e.g., MetaMask).
+Use the buttons below to add Ethereum A1 and Taiko A1 to any wallet that supports `wallet_addEthereumChain` (for example, MetaMask).
 
 | Network     | Add to wallet                                                   |
 | ----------- | --------------------------------------------------------------- |

packages/website/docs/alpha-1-testnet/deploy-a-contract.md

@@ -26,6 +26,6 @@ These steps will show you how to deploy a smart contract to Taiko A1 using Found
    ```
    Note: Remove "<" and ">" from <YOUR_PRIVATE_KEY>
 
-We are using the `--legacy` flag because EIP-1559 is currently disabled on Taiko. We have plans to re-enable it in the future.
+We're using the `--legacy` flag because EIP-1559 is currently disabled on Taiko. We've plans to re-enable it in the future.
 
 You can use the block explorer to verify that the contract was deployed: https://l2explorer.a1.taiko.xyz/

packages/website/docs/alpha-1-testnet/get-help.md

@@ -7,6 +7,6 @@ sidebar_position: 8
 Here are two places for you to get help:
 
 - [Post your question on GitHub Discussions](https://github.com/orgs/taikoxyz/discussions/new?category=questions)
-- [Chat with us on Discord](https://discord.gg/taikoxyz)
+- [Chat on Discord](https://discord.gg/taikoxyz)
 
 GitHub Discussions is preferred because your question might help others who are also running into the same issue. Conversely, you might find the answer to your problem here!

packages/website/docs/alpha-1-testnet/request-from-faucet.md

@@ -4,11 +4,13 @@ sidebar_position: 2
 
 # 💧 Request from faucet
 
-## Request ETH
+**ETH**
 
-- Request ETH from Ethereum A1: https://l1faucet.a1.taiko.xyz/.
-- Request ETH from Taiko A1: https://l2faucet.a1.taiko.xyz/.
+- Ethereum A1: https://l1faucet.a1.taiko.xyz/
+- Taiko A1: https://l2faucet.a1.taiko.xyz/
 
-## Request HORSE
+**HORSE**
 
-- Select HORSE from the token dropdown on the [bridge](https://bridge.a1.taiko.xyz/) and a faucet button should appear.
+1. Visit the [bridge](https://bridge.a1.taiko.xyz/)
+2. Select the network as Taiko A1 and the token dropdown as HORSE
+3. Click the faucet button that appears

packages/website/docs/alpha-1-testnet/run-a-node.md

@@ -9,19 +9,19 @@ This is arguably the most important part of the testnet! Taiko is fully decentra
 Follow the guide at [simple-taiko-node/README.md](https://github.com/taikoxyz/simple-taiko-node/blob/main/README.md) to get started.
 
 :::note
-You will only be able to run a node regularly or as a proposer. In this testnet we are not running any provers.
+You will only be able to run a node regularly or as a proposer. In this testnet we're not running any provers.
 :::
 
 ## System requirements
 
-Because we are a fork of geth, you can consult the [geth minimum requirements](https://github.com/ethereum/go-ethereum#hardware-requirements), which are outlined below.
+Because we're a fork of Geth, you can consult the [Geth minimum requirements](https://github.com/ethereum/go-ethereum#hardware-requirements), which are outlined below.
 
 ### Minimum:
 
 - CPU with 2+ cores
 - 4GB RAM
 - 1TB free storage space to sync the Mainnet
-  - (**only ~50GB for Testnet**)
+  - (**only ~50GB for the Taiko A1 testnet**)
 - 8 MBit/sec download Internet service
 
 ### Recommended:

packages/website/docs/alpha-1-testnet/start-here.md

@@ -6,7 +6,7 @@ sidebar_position: 0
 
 Welcome to Taiko's Alpha-1 testnet, **Snæfellsjökull**. There are two networks involved in the testnet, which we'll define:
 
-- **Taiko A1** is the Alpha-1 testnet release of Taiko — a fully decentralized, Ethereum-equivalent ZK-Rollup.
+- **Taiko A1** is the Alpha-1 testnet release of Taiko: A fully decentralized, Ethereum-equivalent ZK-Rollup.
 - **Ethereum A1** is Taiko's privately deployed Ethereum network, which serves as the L1 for Taiko's Alpha-1 testnet.
 
 ## What can I do?
@@ -15,7 +15,7 @@ In this testnet, you can:
 
 - 🌉 Bridge tokens between Ethereum A1 and Taiko A1.
 - 🤝 Send transactions (e.g., deploy contracts).
-- 🌐 Run a node — this makes **you** a part of Taiko!
+- 🌐 Run a node—this makes **you** a part of Taiko!
 - 📝 Submit feedback and be forever loved.
 - 🥇 Earn a POAP by using your wallet to complete any 2 of the 3 following actions by January 31st 23:59 UTC:
   - Use the bridge

packages/website/docs/alpha-1-testnet/use-the-bridge.md

@@ -27,4 +27,4 @@ L2: https://l2explorer.a1.taiko.xyz/address/0xb8ea36284d1fa062cc0c969e28a49f3531
 
 ## Bridge contract explained
 
-Read the bridge documentation on our GitHub: https://github.com/taikoxyz/taiko-mono/tree/main/packages/protocol/contracts/bridge.
+Read the bridge documentation on GitHub: https://github.com/taikoxyz/taiko-mono/tree/main/packages/protocol/contracts/bridge.