https://github.com/cowprotocol/docs-v2/blob/cd2883a75475f366c4628ac653c74eb6faf5cb66/docs/cow-protocol/concepts/batch-auctions/how-batch-auctions-work.md?plain=1#L11

This looks like a very implementation specific sequence diagram of our low level off-chain components. In a file that attempts to document the high level workings of a batch auction, we should use something less technical and more high level.

Background

Docusaurus is only configured for basic development. Production hardening is required.

Details

Configure docusarus to be in a production ready state.

Acceptance criteria

• #17
• #18
• chore: integrations enabled
• #20

Background

There is some great material that has been written in notion but has not made it to published documentation.

Details

Documentation related to CoW DAO products that are in production are to be published in their relevant section in the CoW DAO documentation (save infrastructure).

Acceptance criteria

• Documentation from notion is migrated to this repo.
• Documentation that has been migrated is removed from notion to eliminate duplication.

martin: Also the diagram included in this page seems over detailed. It mentions drivers, databases and background fibers when the page is only supposed to explain a broad concept.

https://github.com/cowprotocol/docs-v2/blob/a488ae0330b9cc3aeb59b366c6cbd5baeee8380b/docs/cow-protocol/concepts/batch-auctions/how-batch-auctions-work.md

Background

The docs are super nice and use links to get you to places with more info on some topics but because links are only identifiable as such by hovering over them you can probably not notice lots of links.
Basically you currently have to hover over every word in order to not miss any links.

Acceptance criteria

Links are immediately identifiable as such (or at least you should not have to hover over them to detect them).

With reference to:

https://github.com/cowprotocol/docs-v2/blob/df13deca3210c8fada6ea4f4155a0863e680b40a/docs/cow-protocol/concepts/batch-auctions/why-batch-auctions.md?plain=1#L13-L15

I think that full stops should be at the end of a bullet point where the bullet point itself is a full sentence. If it is a list of individual, unrelated "things", then no period at the end of the bullet point. For example:

1. Something
2. Another thing
3. Aardvarks

However, if the bullet points / lists are actual sentences, such as:

1. An example of a full sentence is here.
2. CoW is going to the moon...of Jupiter or Saturn.
3. Didn't think I was going to forget that full stop!

Background

It's common for new projects to launch, and bring about novel ways of handling liquidity / tokens. Often these then trade on secondary markets via AMMs, however the AMMs don't deliver the best value.

Details

It should be communicated to token distributors / projects what the requirements are for their token to be tradeable via CoW, and also how to to about integrating with solvers.

Acceptance criteria

• Instructions for minimum liquidity
• Instructions for integrating with solvers
• Instructions for requesting addition to token lists

Problem

We are creating tutorials for all basic order types the our main UI provides, but TWAP

Suggested solution

Add TWAP

Alternatives considered

Consider TWAP not a core protocol order type and therefore don't create a tutorial, but that seems wrong to me.

Additional context

We might already have a medium guide for this

Acceptance criteria

Have a nice TWAP tutorial page next to Limit Orders and Swaps

https://github.com/cowprotocol/docs-v2/blob/bf73c4804e225abcd2443c0806b40d2228b9bd01/docs/cow-protocol/concepts/batch-auctions/mev-protection.md?plain=1#L7

This part is mentioning in one sentence how we protect from MEV in the absence and presence of CoWs. I think we should have sections that explain both of the two protection in detail (with example transactions for both).

• One transaction where the user set a large slippage but the solver set a tight slippage
• One transaction where the solver got sandwiched (but the user got a better price)
• One perfect CoW and how transaction ordering is irrelevant (no MEV)

We can potentially also reuse the high level diagram we presented in https://docs.google.com/presentation/d/1AB2Eok6nOuUOAMPqIrgSFhZIg39Tw9jHohMg7H5kF0E/edit#slide=id.ge38a0b1903_0_134

https://github.com/cowprotocol/docs-v2/blob/39232451560e0e396cf373ca142af173afa86aad/docs/cow-protocol/tutorials/cow-swap/limit.mdx#L23

Incorporate the "traffic light UI" we have for limit order's likelihood to be executed in the tutorial.

https://github.com/cowprotocol/docs-v2/blob/ae8e1316e4db5ff899871d76dbb3824be82f506b/docs/cow-protocol/reference/core/auctions/social_consensus.md?plain=1#L20

Probably not having some random AMM on some exotic token qualifies here, instead we should define a list of protocols and base token pairs that need to be considered?

Background

As a user, it is difficult to understand the documentation, and it would benefit from a rewrite. This issue tracks the table of contents.

Details

The table of contents (for "CoW Protocol") has been rewritten on an "Action" basis, ie. "What am I trying to achieve?", making it more logical to allow users to drill through their desired action.

Acceptance criteria

• Logical table of contents is established.

Problem

A clear and concise description of what the bug is.

To reproduce

If you can reproduce the behaviour, steps to reproduce:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behaviour

A clear and concise description of what you expected to happen.

Screenshots/logs

If applicable, add screenshots or logs to help explain your problem.

docs version/commit hash

State the version of docs where you've encountered the bug or, if built off a specific commit, the relevant commit hash.

• e.g. v0.9 or ed53bcd

Additional context

Add any other context about the problem here.

Problem

No analytics

Suggested solution

Add analytics

Alternatives considered

Google analytics

Additional context

I just added some env variables with the values of the GA-4. It will automatically pick the right one depending on the environment

Problem

The approval warning is a reusable component that reads token and spender from its props. However when it gets rendered it doesn't actually fill in those values and instead literally displays {props.token} which is not desired.

Example on this page: https://github.com/cowprotocol/docs-v2/blob/main/docs/cow-protocol/tutorials/cow-swap/swap.mdx

This graph;

https://github.com/cowprotocol/docs-v2/blob/6c6e7477506a4ac2d709042ece80ef2e1b4ef0ed/docs/cow-protocol/concepts/batch-auctions/how-batch-auctions-work.md?plain=1#L11

is not discussed in the text of the page. And without discussion, it is impossible to understand what it represents (what is an autopilot?, what is driver0 and driver1?). It feels misplaced: I suggest dropping it or moving it to the technical references

https://github.com/cowprotocol/docs-v2/blob/2bda7a60d5f3b26e8dd6fcbedcd45294ba72498b/docs/cow-protocol/concepts/introduction/flow-of-an-order.md?plain=1#L13

The diagram is missing the fact that solvers report a score back to the auctioneer and the auctioneer tells the winning driver to execute. Moreover, the settlement isn't executed by the solver engine but by the driver component direclty.

https://github.com/cowprotocol/docs-v2/blob/ae8e1316e4db5ff899871d76dbb3824be82f506b/docs/cow-protocol/tutorials/cow-explorer/README.mdx#L12

Should contain examples on:

• How to see the status of my order (how much surplus I got)
• Retrieve the batch I was executed in (other traders, show the graph)
• See partial executions of my limit orders

https://github.com/cowprotocol/docs-v2/blob/3fad222adcd7797919d4a7bd97e03fd7aeb2b574/docs/cow-protocol/concepts/introduction/intents-as-signed-orders.md?plain=1#L6

I'd first focus on the more practical benefits of intents (no fees for for failed transactions, eth-less trades, not committing to a route, slippage being protected by off-chain competition) and only then go into the advantages of batching and offer a whole subsection to CoWs (they are less common, yet a very important differentiation factor to other intent based trading systems).

Inspiration can be taken from the various talks we gave at DevConnect.

https://github.com/cowprotocol/docs-v2/blob/6c6e7477506a4ac2d709042ece80ef2e1b4ef0ed/docs/cow-protocol/concepts/batch-auctions/better-execution-prices.md?plain=1#L5

How is this page different from https://beta.docs.cow.fi/cow-protocol/concepts/introduction/intents ?

It seems to contain the same information in different words, ie

• Explanation of CoWs
• Advantages of gas saving
• Reference to barter economy

Problem

Nowhere do we explain the concept of the programmatic order, watch-tower, etc as a high level product feature

Suggested solution

Add a section Under Concepts -> Product Features -> Builder Friendly

Additional context

While we go into details on this feature in the tutorials section, I feel like it also is a higher level product feature that should be discussed.

Reading "fully permissionless" I wonder how much this documentation should reflect the current status quo vs. the intended long term design. People may argue that the protocol isn't fully decentralized yet.

https://github.com/cowprotocol/docs-v2/blob/763167a3ce1e9438525dbdf0b5b4d58e02575194/docs/README.md?plain=1#L14

It's the first mention of tokenomics and not clear to me how tokenomics ensure the best solution wins (in my mind it's the auctioneer). Otherwise, are we on Gnosis Chain (where no CoW rewards exist) not guaranteed best order settlement?

https://github.com/cowprotocol/docs-v2/blob/01ba96d5c64369fd4dda57196e1736f633a55f31/docs/cow-protocol/concepts/introduction/benefits.md?plain=1#L19

Background

We added a new security-related page to the old docs.

Details

We should include the new page in the docs v2. As this involves a security issue, it's important to keep users informed about it.

Acceptance criteria

• EIP-1271 security issue is fully documented in the docs v2.

Background

Currently the site structure inside the Custom Integrations secition is very messy.

Details

I'd suggest to separate first by type of tutorial, e.g.

• Placing An Order
• Metadata
• Programmatic Orders
• Hooks
• Analyze Auctions

And within each of those section offer tutorials in different flavors. E.g. for placing an order

• Using the SDK
• Using the API
• Using a python script
• etc

Analyze auction could have a tutorial using the Graph, Dune and potentially our swagger endpoint.

The first two paragraphs of this page try to connect PBS and batch auctions (by viewing the block as a batch, I guess). This connection is difficult to grasp and also too high level for this part of the documentation. I suggest dropping the initial two paragraphs, and start with "In a batch auction, first the protocol gathers intents..."

https://github.com/cowprotocol/docs-v2/blob/6c6e7477506a4ac2d709042ece80ef2e1b4ef0ed/docs/cow-protocol/concepts/batch-auctions/how-batch-auctions-work.md?plain=1#L7-L9

Links to be fixed for "MEV Blocker", "CoW Grants Program, the CoW Protocol Explorer, and the CoW Swap frontend"

https://github.com/cowprotocol/docs-v2/blob/763167a3ce1e9438525dbdf0b5b4d58e02575194/docs/README.md?plain=1#L10C49-L10C49

Background

At the start of the documentation, after the landing page, we introduce Concepts. This is from a high level perspective.

Details

This section is to be owned by Marketing, and cross-checked by Engineering for (sanity checks / veracity only).

Acceptance criteria

• Introduction
• Batch Auctions

NOTE: Update the acceptance criteria above if the documentation structure changes to reflect such.

Background

Currently the documentation is implemented in Gitbook. While this provides a simple UI for non-technical content editors, it introduces issues associated with artifacts in markdown, vendor lock-in, integration dependencies etc.

Details

It is desired to implement the new docs site using docusaurus, as done by competitors and large open-source projects.

Acceptance criteria

• #13
• #3

Background

It will be more difficult for robots to index the documentation site if they don't get correct metadata.

Details

Using front matter, correctly define the meta data for each page.

Acceptance criteria

• description metadata set
• keywords metadata set

Background

https://beta.docs.cow.fi/cow-protocol/reference/core/auctions/the-problem reads unnecessarily mathematical (e.g. why do we define the order as an n dimensional vector with two elements set) and not really practical for anyone trying to actually understand what the system is trying to enforce. It doesn't for instance mention user balances (endowments) which may not be available for the orders they placed

Details

I'd suggest rewriting this section making it more practical (what do we actually enforce, vs what are soft criteria) and less math heavy.

Acceptance criteria

Someone without a strong math background can get a clear picture of what solvers need to optimize.

I think each of the different types of CoWs should be accompanied with an example transaction and asset flow visualisation highlighting the savings.

https://github.com/cowprotocol/docs-v2/blob/763167a3ce1e9438525dbdf0b5b4d58e02575194/docs/cow-protocol/concepts/introduction/intents-as-signed-orders.md?plain=1#L14-L19

For ring trades, I'd also differentiate between perfect ring trades (rare) and imperfect ring trades that still allow price improvements because tighter markets on the "missing hop" of the ring exists.

E.g https://etherscan.io/tx/0xc9ddbcc88d1a40863013c7c4d4650cd215dd0a9c79dc69ce88f04a6650197101: Here we can CoW the USD(C/T)<>RBN leg (which normally trades at 0.3% fee) and close the missing link (USDC<>USDT) with a Balancer pool that only has a 0.01% fee).

Also a nit, but I believe bullet point lists with one item are frowned upon in some parts of the world.

Alternatively you may wish to integrate CoW Protocol directly into your wallet interface.

Propose to add:

", please reach out to [email protected]."

Because this would most likely require integration discussion to support them.

https://github.com/cowprotocol/docs-v2/blob/458b17a32cccdafed3032b16240fc8c0444c249e/docs/cow-protocol/tutorials/cow-swap/README.mdx#L24

Background

This volume is written on a "action" -> "actor" basis. It provides concrete methodology for how an action is to be performed by the respective actor.

Details

When writing this section, the language should be at most moderately technical, such that it can be expected, given an assumed background of the actor, they will understand.

eg. A user placing an order via the front-end isn't expected to have advanced knowledge of signing methodology, and therefore there is no need to cover highly technical information associated with such.

Acceptance criteria

• Place Orders
  • CoW Swap Front-end
  • SDK
  • Protocol Integrations
• View Orders
  • CoW Explorer
  • SDK
• Solve Orders
  • Running a solver
  • Deploying a solver
• Arbitrate Auctions
  • Autopilot
  • Driver
• Settle Auctions
  • Smart Contracts
• Analyse Auctions
  • Dune Analytics
  • Subgraph

NOTE: Update the acceptance criteria above if the documentation structure changes to reflect such.

Background

Merge conflicts can become a pain. For this reasons, the repository should use one sentence per line.

Details

Ensure that text file formatting does not create merge conflicts.

Acceptance criteria

• One sentence per line across the repository.

Problem

https://github.com/cowprotocol/docs-v2/blob/main/docs/cow-protocol/concepts/product-features/builder-friendly/milkman.md
Contains an image that is partly obscured by an unnecessary arrow.

Problem

I'm frustrated at the lack of information around the architecture for the autopilot / driver system and how various components fit together.

Suggested solution

Document the co-location architecture for autopilot / driver / solver.

Alternatives considered

None. We need this 😅

Additional context

The draft templates (not populated) can be found at https://github.com/cowprotocol/docs-v2/tree/main/docs/cow-protocol/tutorials/arbitrate. Feel free to add in any other documents as needed.

Acceptance criteria

• Populate high level @sunce86
  • Architectural mermaid diagram showing relationship of components
  • Descriptions / overviews of autopilot, driver, solver functionality
  • Sequence diagram of the live of an order (from intent to settlement) - auction abstracted away
  • Sequence diagram of a single auction

Using the template suggested by mfw below:

• Populate driver subpage @MartinquaXD
• Populate autopilot subpage @fedgiac
• Populate solver-engine subpage @fleupold

Review @squadgazzz @narcis96

In the introductory part of the documentation, we refer to solvers as "trusted third parties"

https://github.com/cowprotocol/docs-v2/blob/ee6f5a7e84d20416a1e350a32014fce1ebee02fb/docs/cow-protocol/concepts/introduction/solvers.md?plain=1#L7

They may be now because they are KYCd but the goal is to move to a decentralized/trustless set up (in the sense that misbehaving is prevented by the threat of slashing). I would therefore remove "trusted"

https://github.com/cowprotocol/docs-v2/blob/6c6e7477506a4ac2d709042ece80ef2e1b4ef0ed/docs/cow-protocol/concepts/batch-auctions/why-batch-auctions.md?plain=1#L5

I'd add a diagram show-casing the difference between continuous order books (bid ask spread) vs. discrete order books (orders overlapping clearing at the intersection).

I think we should also add context of why batch auctions are already arguably beneficial in TradFi (we can link/summarize to Budish's talk for that) and highlight more why they make even more sense on Ethereum, namely that there is no concept of continuous time on Ethereum, all transactions within a block are already batched and executed at the same instant in time (yet people apply pseudo-continuous time priority mechanisms to this which is 🤯)

Problem

composable-cow has disparate documentation across hackmd and multiple repositories.

Suggested solution

Pull together documentation and add to a section within docs-v2.

Additional context

• composable-cow
• clogs

Acceptance criteria

• Port architecture documentation
  • Detail specific handling around the salt
  • Merkle roots
• Add cabinet to architecture

Problem

Trying to start to run a solver, or write a solver is already a very difficult problem - and out of date documentation doesn't help 🙃

Suggested solution

Rewrite the "tutorials" section for solvers, also taking into account the new driver/solver colocation architecture.

Alternatives considered

N/A

Additional context

Considerable work has been done consolidating the section from the old documents. Work in this area can be found at https://github.com/cowprotocol/docs-v2/tree/main/docs/cow-protocol/tutorials/solvers.

Acceptance criteria

• Inaccurate information removed from documentation
• Basic tutorial of starting a solver

Add link to Eth-flow (multiple mentions)

https://github.com/cowprotocol/docs-v2/blob/5105ff9b684ef412cd85da023788af1c9ef47103/docs/cow-protocol/tutorials/cow-swap/native.mdx#L12

Problem

Something we had in our old docs is this search box:

I see new docs don't have it yet:

This is really a feature DEVs use and make it more user friendly, it would be nice to not loose this feature.

There's a page related to this in docusaurus:
https://docusaurus.io/docs/search

I would be great to have this feature in the new docs.

Background

It's critical that the landing page for documentation conveys clearly to the user how to use the documentation.

Details

The editors should define the user directions for the documentation.

Acceptance criteria

• Welcome Page
• Clear directions for using documentation