chore: standardisation - Githubissues

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

[x] off-chain / on-chain NOT offchain / onchain
[x] gasless NOT gas free
[ ] hyperlink all EIPs / ERCs
[x] i.e. NOT ie. and e.g. NOT eg.
[x] hyphenation of all ERC/EIP, e.g. ERC-20 NOT ERC20
[x] Enforce styling of "CoW"
[x] SHOULD use "solver engine" NOT "matching engine" (and only use "matching engine" when talking about it in generic terms)
[x] 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
[x] Safe NOT Safe when talking about Safe smart contract wallet
[ ] Use full stops at the end of proper sentences (including bullet points / lists)
[x] 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
[x] Remove emojis at second level
[ ] Consistently capitalise "ETH", unless in code
[x] "Metadata" NOT meta data
[x] 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
[x] 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)
[x] 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

Standardisation for methods of contact. Currently have:

info@cow.fi
bd@cow.fi
Links to discord

What do we want? Should be mostly general in nature and want to be careful about funnels here to make sure they're streamlined.

Comments from Alex

Language:

[ ] Rename "Autopilot" to "Auctioneer"
[ ] Rename "OrderBook" to "order book" (and find consistency of capitalization within the section) ... or, alternatively, pick just one way of styling this term across the docs
[ ] Only capitalize proper nouns (so "batch auctions" not "Batch Auctions", "solver" not "Solver", etc.)
[ ] Remove all overly-salesy language, including (all?) exclamation points. For example, this: "Integrate the power of CoW Swap into your product! With the widget, you can create an incredible trading interface. Specify the required pair of currencies, customize the look and much more!" (https://docs.cow.fi/cow-protocol/tutorials/widget)
[ ] Update the language used in the ComposableCoW section to what we previously aligned to ("programmatic orders" not "conditional orders" etc.)
[ ] Double-check that we are consistently styling "CoW" as such (...I just found a few "Cow"s)
[ ] Decide if we'd rather use "Eth-flow" (as we do at learn.cow.fi) or "Native tokens" (as we do in tutorials), and stick to one consistently
[ ] (Mindy:) I hate “Eth-flow”. I would much rather it be called “ETH flow” - or better yet, since “flow” is software design lingo, just say something like “Trade with native ETH” or “Have CoW Swap wrap ETH for you.”
[ ] (Anxo:) Don't perpetuate names we don't want to perpetuate (even if they are in the contract). Just for the title and navigation, in the content we can say the contract for the Settlement is actually called GPv2Settlement, or the Programmatic Orders contract are among others ComposableCoW (reference:https://cowservices.slack.com/archives/C04N05LJK54/p1704913923423419?thread_ts=1704913551.975089&cid=C04N05LJK54)

Navigation/Structure:

[ ] Update the logo (top-left) to the CoW DAO logo (i.e. not the CoW Protocol logo)
[ ] No top-level toggle should have content under it. Rationale: (1) users are likely to miss content in these places, (2) we place content here inconsistently and consistency is important, (3) using a toggle item to house content is not standard with how similar projects organize their docs, e.g. Uniswap, 1inch, Flashbots
[ ] "Solver" under "Arbitrate Auctions" has no content under it and is not a toggle (I thought it was broken when I clicked on it 5 times and nothing happened). We should remove it altogether and move "Driver" and "Solver Engine" to the left so they're aligned with OrderBook and Autopilot
[ ] The emojis make the nesting look weird (it looks like the nested items are to the left of the item they are nested under, instead of to the right, which is confusing) ... we should either move sub-items over to the right some more (preferred) or remove the emojis (we could also consider just moving the emojis next to sub-toggles)
[ ] Rename "Welcome" to "CoW DAO" and give it a nice emoji (if we continue using emojis)
[ ] Rename "Introduction" in the concepts section to "Foundational Concepts"
[ ] Consider updating the nav of the tutorials section to just (1) Using CoW Protocol, (2) Integrating CoW Protocol, and (3) Building a Solver -- and nesting all other content under those headers. This is consistent with the way we define our audience groups, and will make this whole section much easier to navigate
[ ] Make it more clear that learn.cow.fi exists, with a sub-item called "Live coding 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)
[ ] Change the name of "Arbitrate Auctions" to something less esoteric like "Overview" or "How it works"
[ ] Either (a) delete CoW Explorer from tutorials, as it is a separate product, or (b) combine all of the sub-pages into one page as it is very confusing to the navigation logic
[ ] Combine some of the content from the solvers section of tutorials with the solvers section of concepts. Specifically, the content here (https://docs.cow.fi/cow-protocol/tutorials/solvers) and here (https://docs.cow.fi/cow-protocol/concepts/introduction/solvers) seems duplicative

To Discuss (Navigation/Structure):

[ ] Move "Arbitrate Auctions" (I'm just not sure if this belongs in tutorials or another section, if it belongs in a group of pages about solvers, if it belongs in a group of pages about integrating the protocol, or if it belongs at the top of this section with a different title - e.g. "Overview")
[ ] Move the "Batch Auction mechanism" section ... this, similar to "Arbitrate Auctions", seems out of place. Maybe the target audience (for both) is people that want to build solvers, and it should be labelled as such.
[ ] Consider removing the tutorial for native tokens. It is not one of our order types, and the content is not so relevant so long after we made the update
[ ] Consider removing the CoW Swap tutorials altogether, as this is docs for CoW Protocol and not docs for CoW Swap (we can repurpose this content in a how-to section on our blog)
[ ] Should we add tutorials for Programmatic Orders, Milkman Orders, and CoW Hooks?
[ ] Can the "SDKs > Namespaces" be consolidated, as there is only one bullet per page? Seems unnecessarily-complex to me as a layman. But also I'm not the audience here, so maybe this is good and standard?
[ ] The SDK toggles are crazy. I assume this is intentional and desirable but I can't find a similar example in the docs of our core competitors. Just flagging it, but maybe it's not so crazy afterall?

Additional Notes:

[ ] CSS issues in the APIs section ... toggle alignment and clipboard graphic on rollover
[ ] Unclear why we use italics here: https://docs.cow.fi/cow-protocol/reference/core/auctions
[ ] See Anxo's notes (orange) here: https://docs.google.com/spreadsheets/d/1CjKzCywvXEblLouPWR1EfhaCdrJstrXCEtxgrQGnZBE/edit#gid=1007826788

From @gogonimago:

Grammar / Semantic Conventions:

[ ] 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
[ ] There should be no periods for the last sentence (or only sentence) in bullet points or enumerated lists, per our user-facing convention
[ ] Currently, "ETH" isn't always capitalized, particularly in Native tokens section: https://docs.cow.fi/cow-protocol/tutorials/cow-swap/native and here: https://docs.cow.fi/cow-protocol/reference/contracts/periphery/eth-flow
[ ] "Metadata" should be one word. Relevant here: https://docs.cow.fi/cow-protocol/tutorials/arbitrate/solver/driver
[ ] 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
[ ] 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. 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

One-offs:

[ ] In https://docs.cow.fi/cow-protocol/tutorials/arbitrate/orderbook, "most traders want to see an estimate of how much tokens they will receive in order to pick a reasonable limit price" should be "how many tokens" or "how much in tokens"
[ ] 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..."
[ ] Making sure that in https://docs.cow.fi/cow-protocol/reference/core/auctions/rewards "gets rewarded with a fixed 9 COW reward" is indeed what the last sentence should say?
[ ] Should we change Composable CoW to the Programmatic Order Framework or is it still Composable CoW under the hood? https://docs.cow.fi/cow-protocol/reference/contracts/periphery/composable-cow
[ ] Re: Composable CoW, the user-facing convention we used was "WatchTower" rather than "Watch-tower"

Nice-to-haves:

[ ] Use em dash "–" in place of normal dash when marking breaks in a sentence
[ ] 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)
[ ] 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"
[ ] In the "placing a TWAP order" page, the "🔌 With your Safe wallet, open CoW Swap (Safe App)" bullet point should be more of a first sentence of the section, it's not congruent with the previous bullet

Thank you!

cowprotocol / docs

chore: standardisation #225