originprotocol / origin-docs-archived

We've moved to a monorepo: https://github.com/OriginProtocol/origin/tree/master/docs

This repo is no longer active. Please go to https://github.com/OriginProtocol/origin

origin-docs-archived's Issues

Messaging

Don't forget to document (and potentially improve) the messaging API. 🐘

Add code style guides to the 'Contributing' section of our docs

We should give better instructions for developers who are new to project to get started. Including our various style guides, how to go about claiming an issue, how to request feedback, etc.

Update css to better match website

A bigger makeover is needed someday, but for now the following would go a long way:

• Use Lato and Poppins fonts for body/headings
• Set background colors to match palette of company website.

@micahalcorn - I know you're busy, but could you take stab at this? I can also do it.

Document new purchase stages

Since the purchase stages have been changed, this should be updated in the docs.

Add links to the Discord on the contribute page

Make the discord easy to find from the docs.

Nonunique subheadings link incorrectly

There is a fix for this in the lord/slate master branch. @wanderingstan is there a convenient way to fast-forward our branch to include some of their changes, or would you like me to make a PR with the NestingUniqueHeadCounter class manually added? I've tested and it fixes our problem.

Document new arbitration methods

Once OriginProtocol/origin-js#279 is completed, the new purchase-related arbitration methods should be documented.

Add the Origin favicon to the docs

Improve sample listing in code example

In conjunction with #11, the sample listing should be improved to include [an/ideally multiple] image[s].

Edit docs for new branching workflow

http://docs.originprotocol.com/#local-development

The docs currently have instructions for how to develop locally using the develop branch. They should be changed to use our new branching model, using master.

Small issue : the word "javascript" on mobile docs

The word "javascript" seems to appear in the top left hand of the main page of the docs on mobile. Right next to the search box. http://docs.originprotocol.com

Seen on:

• mobile Safari on Apple iPhone 6s running Version 11.4.1
• mobile Chrome Version 68.0.3440.83
• mobile Opera 16.0.12

cc @DanielVF

Document new listing methods

Since two new listing methods have been added to the API, they should be added to the docs.

Document identity API

As #22 on the bridge server is completed, confirm that the new identity API is documented here in the docs.

Detach from lord/slate

This repo gets "contaminated" with activity on the upstream lord/slate repo.

We should detach it and make standalone.

Attestations: document data, claim type, and signature properties

We should clarify the significance of each of these properties. For reference, these are specified as part of ERC735.

We should keep in mind, and probably note in the docs, that an understanding of these properties is not required in order to use the API. They are simply used for validation and origin-js does all the validation behind the scenes. (Invalid attestations will never show up in the user object that is returned from the get method.) Our explanation should be provided simply to satisfy the curiosity of developers and provide transparency in our implementation. 😃

🎓Replace Slate as our documentation system?

I think Slate won't scale as our documentation system. Slate is designed to generate a giant single page document, and maxes out at two levels of headings for navigation.

Our Origin docs need to document more than one origin system, which doesn't fit into Slate's navigation model, and having everything in one page is already unwieldy at the current size of our documentation.

We need to control the page hierarchy/navigation, and that's fundamentally not what Slate is about.

Here's what I'd like to see:

• Multi page documentation
• We control menu/navigation
• Markdown based. We all speak it.
• Prefer including arbitrary markdown files, vs one fixed directory that docs live in. With a monorepo this would let us keep docs with their own projects, and yet build a single documentation site from it.
• Support for code highlighting
• Nice to be Javascript or python based. (but speed and fewer dependencies are far more important)

Thoughts?

---

Documentation systems:

• https://www.mkdocs.org/
• http://www.sphinx-doc.org/ (would use markdown support)

More generic systems:

• https://gohugo.io/
• https://www.gatsbyjs.org/
• https://jekyllrb.com/
• http:/getpelican.com/
• https://vuepress.vuejs.org/

Others?

Document reviews-related methods

Once https://github.com/OriginProtocol/origin-js/issues/149 is completed, document the new methods in the relevant section.

Need separate API section

Right now our origin.js API documentation is just mixed in with the rest of the docs. We have sections for things like Users and Listings, but these sections are at the same level as other sections such as Introduction. We really need a section called API that makes it clear what part of the docs pertains to the API. Either that, or we may eventually need separate documentation for the API. 🤔

Add code examples to our docs using jsfiddle.com or something similar

Let's add some simple working examples using jsfiddle.com or a similar code playground tool.

Notifications API

Once OriginProtocol/origin-js#222 is merged, the Notifications API should be documented.

Improve CodePen Examples

Now that CodePen examples have been added, they need to be less fragile. They currently detect whether or not the reader has a web3-enabled browser and, if not, suggest MetaMask. They don't, however, detect whether or not a MetaMask user is signed in, or validate the currently-selected network. To resolve this issue, fork each of our CodePens and add the following:

• Move web3 detection into another Pen that is added as an "external resource" in each forked Pen
• In the external Pen, detect that web3 is set to the Rinkeby network validation and serve an appropriate message if it is not
• In the external Pen, detect that a web3 account is available and serve an appropriate message if it is not

Heading anchors don't quite work with CodePen examples

Since we embedded CodePen examples, the page jumps after the first rendering. This causes a bad experience when someone arrives on the docs via a deep link or heading anchor. For example, click http://docs.originprotocol.com/#review and you will likely end up seeing something unexpected about purchase methods (depending on the size of your screen).