chore: standardisation

Background

As we near the end of the docs cycle, to bring about standardisation, this issue tracks global search/replace nomenclature issues.

Details

Upon completion of this epic, we should have consistent wording across the entire documentation.

Acceptance criteria

Search-replace Tasks

• off-chain / on-chain NOT offchain / onchain
• gasless NOT gas free
• hyperlink all EIPs / ERCs
• i.e. NOT ie. and e.g. NOT eg.
• hyphenation of all ERC/EIP, e.g. ERC-20 NOT ERC20
• Enforce styling of "CoW"
• SHOULD use "solver engine" NOT "matching engine" (and only use "matching engine" when talking about it in generic terms)
• approve only to refer to a type of on-chain transaction (ie. actually calls .approve()) (which is signed and created according to the above)
• one sentence per line in source code (reduces merge conflicts later down the line). Will look exactly the same
• Safe NOT Safe when talking about Safe smart contract wallet
• Use full stops at the end of proper sentences (including bullet points / lists)
• Order book NOT OrderBook
• Use proper spacing / capitals of names of components unless used referring to specific in-code then MUST be in fixed-width font
• Remove all variable width occurences of EthFlow and prefer to use "Native token support" where possible
• Remove emojis at second level
• Consistently capitalise "ETH", unless in code
• "Metadata" NOT meta data
• Remove italics here: https://docs.cow.fi/cow-protocol/reference/core/auctions
• In the concepts section we opted to say "EOA's" rather than injected wallets, so we should make sure we only using "injected" where technically necessary and using "EOA" the rest of the time
• Use "watch tower" NOT watchtower / WatchTower
• The convention we're going with is to keep "solvers" lowercase. Relevant here: https://docs.cow.fi/cow-protocol/reference/core/auctions
• Convention is to keep "protocol" lowercase. Relevant here: https://docs.cow.fi/cow-protocol/reference/core/auctions and here; https://docs.cow.fi/cow-protocol/reference/contracts/core/settlement
• The beginning of a sentence after a colon should be capitalized, unless it is a continuation of that sentence. Relevant here: https://docs.cow.fi/cow-protocol/reference/core/auctions/the-problem and here: https://docs.cow.fi/cow-protocol/reference/core/auctions/competition-rules
• The beginning of a sentence in a bulleted or numbered list should be capitalized. Relevant here: https://docs.cow.fi/cow-protocol/reference/core/intents and here: https://docs.cow.fi/cow-protocol/reference/core/tokens
• All references to CIP's should be linked with the snapshot CIP. Relevant here: https://docs.cow.fi/cow-protocol/reference/core/auctions/competition-rules
• The list under "Governance" here: https://docs.cow.fi/cow-protocol/reference/core/auctions/competition-rules should use colons after the parenthesis - ex: "(CIP-11: Uniform clearing prices...)"
• Use the Oxford comma – put a comma before the "and" in a given list
• Ensure all quoted items are double quotes (in CoW Explorer, "view fills" is in single quotes: https://docs.cow.fi/cow-protocol/tutorials/cow-explorer/order)
• For markdown, write "" and not “”
• On pages with a single footnote, it would look better if the footnote were just an in-line, parenthetical aside: https://docs.cow.fi/cow-protocol/tutorials/cow-explorer/order
• Instead of "where one" when reference a person, let's simply say "where a user"
• Only capitalize proper nouns (so "batch auctions" not "Batch Auctions", "solver" not "Solver", etc.)

Writing

• #313
• #314
• #315
• Standardize the content structure for each of the tutorials. (The copy for tutorials should be organized as consistently as possible, with the same or similar H2s across each toggle set ... right now, for example, some start with "Introduction" and some do not, and some say "place a ____ order" while others say "placing a ____ order" and some sections are written in the 2nd person while others are written in the 3rd person). Looking at all of the tutorials together, I would suggest the following structure:
  • (introduction that does not use "Introduction" as a sub-header; the introduction should quickly overview what this type of order is and the benefits of the order type - i.e. why someone would want to use it. It can link to the matching part of the concepts section to save space)
  • "Place a ____ order" (for duplicated content, do it with partials)
    • Connect wallet
    • Select tokens
    • Etc.
    • Confirm ____ order
  • "Track a ____ order"
  • "Cancel a ____ order"
  • (no conclusion)
• The arbitrate auctions section as a whole could use a re-read for various missing commas, dangling modifiers, and other grammatical fixes. It departs from the style of the other sections so I assume it was written by someone other than @mfw78

Rearrange / structure

• #316
• #317
• #318
• #319
• #320
• #321
• #322
• Issues reported in https://github.com/cowprotocol/docs/issues/281 (except for partially-filled NOT partially filled)

Repository setup

• Apply standard linting across repo
• All screenshots to use lazy load ideal image
• Update the logo (top-left) to the CoW DAO logo (i.e. not the CoW Protocol logo)
• Link to learn.cow.fi in the header of docs