Cosmos SDK Liquidity Module docs review/QA

[minkyraccoon]

The aim of the epic is to QA the documentation artifacts that form part of the Liquidity module. This includes the following

• PRIMARY FOCUS: Liquidity Module Spec Markdown docs
  ongoing in docs: Liquidity Module editorial review and many questions  #201
• Swagger HTTP API doc (2.1.1)
  review cycle complete in Cherry-pick Suggestions for Swagger documentation QA (2.2.1) #214
• Tendermint published godoc
• Liquidityd Client CLI doc Markdown
  first review cycle complete in go files, PR docs: Liquidity Pool liquidityd command line help Client CLI Documentation QA #212

Note, Litepaper has been QA separately.

• Liquidity Module Lite Paper (English) source and PDF

Issues are raised for each documentation area

Outcomes of each issue will include

• Edits suggested via PR
• Comments that will outline areas for improvements and identify
• It may also include plans for remediation and how to write better documentation

[barriebyron]

to help with EcoDev planning, can you let @Tosch110 and me know what the target due date is?

[barriebyron]

Status on Friday April 9

is pool-type-id flag the same thing as pool-id? I see an opportunity for clarity.

Liquidity Module Spec Markdown docs

• #201

• Extensive first-round and second-round editorial work complete. I still lack a fundamental understanding of how cool the liquidity pool module is, forgive my "I'm still learning" state.

• Several outstanding questions remain open in the Files Changes view.

Liquidity Pool liquidityd command-line help Client CLI Documentation QA

• #212

• First and second rounds complete. Excellent progress getting each flag explained, see [this comment](https://github.com/tendermint/liquidity/pull/212/files#diff-3d2dbc99856e2b9dd214922be356cf8e80279c9a6d411e38a149f600d2bc346eR45

Swagger

• #206 is in draft status. Some of the required changes look so familiar, I am wondering if we shouldn't merge and open a new PR. Backstory, the original PR was merged before I looked at every detail. Let's open a new PR if needed. I see repetitive changes that we can iterate on.

godoc

• #217 remind me what a godoc is and how we expose it? purpose/audience? Next up!

[barriebyron]

Now that the liquidity module is ready to be merged, here's a summary of where we are with the docs work:

PR 201 client.md, query.go, tx.go

#201 ready for final review

• first edit iteration that never got merged or approved

doc/client.md
x/liquidity/client/cli/query.go
x/liquidity/client/cli/tx.go 

• just one broken link for SwaggerHub API docs needs attention, maybe @kogisin can address?
• this state is a good basis for future iterations
• README edits are incomplete, we have a few competing PRs for that work, so let's do this:
  • merge this PR and then get the README text changes from https://github.com/tendermint/liquidity/pull/234/files/d70413c44113c04a97c1ebc8035852529b0527f1#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5 and the README CLI changes from the generated code (or client.md file, whatever works on your end)

PR 217 go docs need more file links

#217 is edited and approved (by me) I will edit more files, but I am not clear on what files, please provide links

PR 356 swagger.yaml

I moved swagger.yaml edits to this new PR based off of the develop branch so we can iterate more quickly
#356

---

I realize we have a lot of loose ends, so to expedite the liquidity module docs merge mission, we can always agree to iterate and improve.

Questions? please ask. I'm open to ideas and suggestions (let's not do this long-running, wide-scope PR again, let's use smaller PRs with more manageable content reviews)... we are all learning here. Thank you for your patience.
@SenorMonito FYI for status

[jaybxyz]

Thanks for the status. I will update the broken link for SwagerHub API docs today.

let's use smaller PRs with more manageable content reviews)...

This will certainly speed up the process.