[R4R] ADR: New docs structure #2696

gamarin2 · 2018-11-05T19:50:02Z

This PR proposes a new structure for SDK docs that we discussed with @zramsay. It would clear the SDK repo of unnecessary content and would make it much easier for devs to find what they need to update. It would also help if we want to have executable documentation in the future (cc @cwgoes).

Here are the current steps for the docs refactor #2697

codecov · 2018-11-05T19:56:11Z

Codecov Report

Merging #2696 into docs-overhaul will not change coverage.
The diff coverage is n/a.

@@              Coverage Diff               @@
##           docs-overhaul    #2696   +/-   ##
==============================================
  Coverage          58.01%   58.01%           
==============================================
  Files                153      153           
  Lines               9511     9511           
==============================================
  Hits                5518     5518           
  Misses              3632     3632           
  Partials             361      361

zramsay · 2018-11-05T19:58:25Z

docs/architecture/adr-002-docs-structure.md

+
+The files in each sub-folders do not matter and will likely change. What matters is the sectioning:
+
+- `README`: Landing page of the docs. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/pulls) will be highlighted, as well as the `godocs`.


rm /pulls from the link

This is great. Like the areas highlighted here!

zramsay · 2018-11-05T19:59:16Z

docs/architecture/adr-002-docs-structure.md

+
+- `README`: Landing page of the docs. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/pulls) will be highlighted, as well as the `godocs`.
+- `gaia`: Contains all docs related to the `gaia` application. Will later be renamed to `cosmos-hub` or `chub` and probably moved to its own repository.
+- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 


what about swagger? https://cosmos.network/rpc/

in the clients section

you think we should ditch the /rpc/ endpoint on the site?

Not necessarily. The swagger doc can be linked from the clients section. I don't think swagger doc can be integrated in a vuepress site, or can it?

zramsay · 2018-11-05T20:00:10Z

docs/architecture/adr-002-docs-structure.md

+- `README`: Landing page of the docs. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/pulls) will be highlighted, as well as the `godocs`.
+- `gaia`: Contains all docs related to the `gaia` application. Will later be renamed to `cosmos-hub` or `chub` and probably moved to its own repository.
+- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 
+- `examples`: Contain a couple examples of sdk application liker `bascoin` and `democoin`. Developers need to maintain them up-to-date and make sure they compiles as the SDK gets upgraded.


liker, bascoin

keep them up-to-date ... compile

zramsay · 2018-11-05T20:00:25Z

docs/architecture/adr-002-docs-structure.md

+- `gaia`: Contains all docs related to the `gaia` application. Will later be renamed to `cosmos-hub` or `chub` and probably moved to its own repository.
+- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 
+- `examples`: Contain a couple examples of sdk application liker `bascoin` and `democoin`. Developers need to maintain them up-to-date and make sure they compiles as the SDK gets upgraded.
+- `clients`: Contains specs and infos about the various SDK clients.


zramsay · 2018-11-05T20:01:05Z

docs/architecture/adr-002-docs-structure.md

+- Intro (`README`)
+- `gaia`
+- `reference`
+- `clients`


why only these three?

explained just after

zramsay · 2018-11-05T20:01:40Z

docs/architecture/adr-002-docs-structure.md

+- `reference`
+- `clients`
+
+`architecture` and `examples` need not be displayed on the website. As for `modules`, we might need to think about creating a modules manager, but this is out of scope for this document.


the files get rendered by virtue of being .md files, so they're accesible by default, even if not linked in the sidebar

sure, this is what matters (that they're not in the sidebar)

Agree with @gamarin2 here

zramsay · 2018-11-05T20:02:12Z

docs/architecture/adr-002-docs-structure.md

+
+### Neutral
+
+- We need to move a bunch of deprecated stuff to `/attic` folder. 


zramsay

we should add a section about swagger and the lite RPC. also would be good to mention the DOCS_README.md somewhere

zramsay · 2018-11-05T20:04:01Z

docs/architecture/adr-002-docs-structure.md

+### Neutral
+
+- We need to move a bunch of deprecated stuff to `/attic` folder. 
+- We need to port most of the content in `docs/sdk/docs/core` in `reference`.


ah, hm, i moved that into _attic FTTB

sure, let me rephrase. For now, _attic, but the content is good and most of it could fill parts of the reference

jackzampolin

A couple of small comments, but this looks great! Can't wait to see implementation here.

jackzampolin · 2018-11-05T21:12:53Z

docs/architecture/adr-002-docs-structure.md

+│   ├── basecoin/
+│   └── democoin/
+├── clients/
+│   ├── lite/


What about the CLI client?

Sure, this tree is not the definitive docs tree, just a more or less accurate example! what matters are the section.

jackzampolin · 2018-11-05T21:15:01Z

docs/architecture/adr-002-docs-structure.md

+│   ├── validator-node.md
+│   ├── validator-faq.md
+│   └── delegator-faq.md    
+├── reference/


This looks like all new content?

Hmm I presume this is the old SDK spec?

no, the spec should stay in the same place

jackzampolin · 2018-11-05T21:15:36Z

docs/architecture/adr-002-docs-structure.md

+- `reference`
+- `clients`
+
+`architecture` and `examples` need not be displayed on the website. As for `modules`, we might need to think about creating a modules manager, but this is out of scope for this document.


Agree with @gamarin2 here

cwgoes

A few comments. I'm not sure this should be an ADR - it might be nice if we keep ADRs to decisions about the technical architecture of our code, instead of the documentation, as the latter isn't necessarily relevant to the target audience (someone trying to understand our decisions or reimplement parts of our work elsewhere).

cwgoes · 2018-11-06T10:17:48Z

docs/architecture/adr-002-docs-structure.md

+│   ├── validator-node.md
+│   ├── validator-faq.md
+│   └── delegator-faq.md    
+├── reference/


Hmm I presume this is the old SDK spec?

cwgoes · 2018-11-06T10:18:37Z

docs/architecture/adr-002-docs-structure.md

+- `reference`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. 
+- `examples`: Contain a couple examples of sdk application like `basecoin` and `democoin`. Developers need to maintain them up-to-date and make sure they compile as the SDK gets upgraded.
+- `clients`: Contains specs and info about the various SDK clients.
+- `modules`: Contains specs of modules.


gaia modules, right (like we have at the moment)?

Yes. Until we figure out a better decision for module management.

cwgoes · 2018-11-06T10:19:35Z

docs/architecture/adr-002-docs-structure.md

+
+### Neutral
+
+- We need to move a bunch of deprecated stuff to `/_attic` folder. 


Can we instead delete it? Git keeps full history, we can always restore it later. Leaving files around in _attic just creates clutter.

gamarin2 · 2018-11-06T10:41:35Z

Where would you put such records then? Tendermint does have ADR related to documentation tendermint/tendermint#2313.

The goal of this doc is to understand why we're making these changes, getting consensus on them and keeping a record. Wdyt @zramsay?

cwgoes · 2018-11-06T10:59:10Z

Where would you put such records then? Tendermint does have ADR related to documentation tendermint/tendermint#2313.

Alternatively we could just put this in a file in the root of the docs folder, but I don't have a strong opinion.

codecov · 2018-11-13T17:02:26Z

Codecov Report

Merging #2696 into docs-overhaul will increase coverage by 0.11%.
The diff coverage is n/a.

@@                Coverage Diff                @@
##           docs-overhaul    #2696      +/-   ##
=================================================
+ Coverage          57.92%   58.03%   +0.11%     
=================================================
  Files                129      153      +24     
  Lines               8270     9511    +1241     
=================================================
+ Hits                4790     5520     +730     
- Misses              3162     3630     +468     
- Partials             318      361      +43

gamarin2 requested a review from zramsay as a code owner November 5, 2018 19:50

gamarin2 force-pushed the gamarin/docs-adr branch from e9596fb to 6905ab9 Compare November 5, 2018 19:56

gamarin2 changed the base branch from develop to docs-overhaul November 5, 2018 19:56

zramsay reviewed Nov 5, 2018

View reviewed changes

gamarin2 mentioned this pull request Nov 5, 2018

Docs refactor process #2697

Closed

zramsay reviewed Nov 5, 2018

View reviewed changes

jackzampolin approved these changes Nov 5, 2018

View reviewed changes

gamarin2 changed the title ~~ADR: New docs structure~~ [R4R] ADR: New docs structure Nov 5, 2018

cwgoes suggested changes Nov 6, 2018

View reviewed changes

jackzampolin mentioned this pull request Nov 8, 2018

Update CLI to match new command structure #2732

Closed

gamarin2 added 6 commits November 13, 2018 18:01

Add adr-002

9636d11

.

0d0d6f0

add adr to new org

c45601e

fix typo

59c18fb

integrate zach review

643f56f

little ficx

1440437

gamarin2 force-pushed the gamarin/docs-adr branch from 93c75fa to 1440437 Compare November 13, 2018 17:02

gamarin2 merged this pull request into docs-overhaul Nov 13, 2018

gamarin2 deleted the gamarin/docs-adr branch November 13, 2018 17:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[R4R] ADR: New docs structure #2696

[R4R] ADR: New docs structure #2696

gamarin2 commented Nov 5, 2018 •

edited

Loading

codecov bot commented Nov 5, 2018 •

edited

Loading

zramsay Nov 5, 2018

jackzampolin Nov 5, 2018

zramsay Nov 5, 2018

gamarin2 Nov 5, 2018

zramsay Nov 5, 2018

gamarin2 Nov 6, 2018

zramsay Nov 5, 2018

zramsay Nov 5, 2018

zramsay Nov 5, 2018

gamarin2 Nov 5, 2018

zramsay Nov 5, 2018

gamarin2 Nov 5, 2018

jackzampolin Nov 5, 2018

zramsay Nov 5, 2018

zramsay left a comment

zramsay Nov 5, 2018

gamarin2 Nov 5, 2018

jackzampolin left a comment

jackzampolin Nov 5, 2018

gamarin2 Nov 6, 2018

jackzampolin Nov 5, 2018

cwgoes Nov 6, 2018

zramsay Nov 6, 2018

jackzampolin Nov 5, 2018

cwgoes left a comment

cwgoes Nov 6, 2018

cwgoes Nov 6, 2018

gamarin2 Nov 6, 2018

cwgoes Nov 6, 2018

gamarin2 Nov 6, 2018

gamarin2 commented Nov 6, 2018

cwgoes commented Nov 6, 2018 •

edited

Loading

codecov bot commented Nov 13, 2018


		The files in each sub-folders do not matter and will likely change. What matters is the sectioning:

		- `README`: Landing page of the docs. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/pulls) will be highlighted, as well as the `godocs`.


		### Neutral

		- We need to move a bunch of deprecated stuff to `/attic` folder.

[R4R] ADR: New docs structure #2696

[R4R] ADR: New docs structure #2696

Conversation

gamarin2 commented Nov 5, 2018 • edited Loading

codecov bot commented Nov 5, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zramsay left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jackzampolin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cwgoes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gamarin2 commented Nov 6, 2018

cwgoes commented Nov 6, 2018 • edited Loading

codecov bot commented Nov 13, 2018

Codecov Report

gamarin2 commented Nov 5, 2018 •

edited

Loading

codecov bot commented Nov 5, 2018 •

edited

Loading

cwgoes commented Nov 6, 2018 •

edited

Loading