Review & re-implement our docs for simplicity and encouraging contribution

[yomexzo]

Considering Github Pages can now be served from the docs directory. We would be moving the content of gh-pages into the docs directory and reformat the docs itself such that it can be browsed from within github without having to visit shopify.github.io/js-buy-sdk/.

The following will need to be done to achieve this:

• Move the gh-pages branch content into docs directory within the master branch and ensure the docs can still be updated as it currently is on gh-pages branch. See Bring gh-pages into /docs folder #201
• Implement generation of API documentation on a per-version basis such that users can still browse older docs. See Implemented generation of API (yuidoc) docs #199
• Implement ability to switch in between various documentation versions
• Update docs content such that they are markdown files that can be easily browsed within the repo on github.
• Fix fetch, fetchAll, fetchAllPRoducts under ShopClient. Currently no documentation exists for those functions but they are in the right hand pane
• Write a copy and paste example which requires no prior knowledge (API keys or Product IDs). Implement into README.md and as first example in Docs
• Update docs with information on ability to sort responses. Detailed at Product Sort Order Within a Collection? #175
• Ensure CONTRIBUTING.MD reflects all changes being made to how to work with the repo

👀 @mikkoh @richgilbank @minasmart @tessalt

[minasmart]

This looks great! One concern regarding:

Implement generation of API documentation on a per-version basis such that users can still browse older docs. See #199

Now that the docs are going to be stored in master, as human readable markdown, should we maybe just link to the tag of the old version? I'm not sure we want to keep growing the repo now that things live in master.

[yomexzo]

@minasmart, I have been thinking of how best to handle that too.

We can link to the tag of the older versions just as you have said and for someone not happy with browsing the src, they can pull the repo, generate the docs using what's in #199 and serve the docs themselves. Of course, we'd provide instructions on how to see older docs in the docs.

This only resolves API docs tho. Not user docs that we write to compliment the API docs.

Another angle is, if we make sure to update the docs before publishing a new version, pulling down the repo, checking out a particular version and serving the docs in the version should reflect exactly the state at the time.

[minasmart]

If the guides are accurate in the tagged version, that should be reflective in the source too.

If we can, at some point in the future write yuidoc to md and have jekyll bring it in, it'll be easier to read all the things, I think.

[yomexzo]

Absolutely. Getting it to write into md is already in the works.

[mikkoh]

@yomexzo do we need to add to the checklist to updates CONTRIBUTING.md? There's mention of where docs live etc.

[minasmart]

I would update all docs that talk about how to build docs. CONTRIBUTING.md is one, but there may be a few sections on the site itself? Not sure.

[yomexzo]

Yeah, absolutely. The whole of the documentation is being reviewed but it might be worth it adding this to the checklist. Doing that right now.

[mikkoh]

Some of these issues will be resolved in this PR #233

[mikkoh]

Finished
"Ensure CONTRIBUTING.MD reflects all changes being made to how to work with the repo"

https://github.com/Shopify/js-buy-sdk/blob/master/CONTRIBUTING.md

Although I'm not sure if you were talking about writing documentation on how to consume the module.

[mikkoh]

@yomexzo once Shopify/yuidoc-lucid-theme#3 is in it'll fix the issue:

Fix fetch, fetchAll, fetchAllPRoducts under ShopClient. Currently no documentation exists for those functions but they are in the right hand pane

[mikkoh]

@minasmart Where do you think?

Update docs with information on ability to sort responses. Detailed at #175

should live?

[minasmart]

We should document that under fetchQuery[Whatever]. We should document all of the query params, and maybe have a guide that mentions sorting or complex queries and points to those functions.

[mikkoh]

I've updated docs with info from #175. I'm going to close this issue since #252 exists.