ordercloud-api / oc-documentation Goto Github PK

1. Go to homepage,
2. Click on 'Intro to OrderCloud' button,
3. Click on first anchor link in the right menu 'Overview', it will scroll you there.
4. Observe the menu item unhighlight
5. Scroll to top of page,
6. Observe other menu item open up

We have talked about linking these to "what is ordercloud" and "getting started with ordercloud" guides respectively.

This guide should probably happen right before authentication since authentication uses clientIDs

We used to pull this version in based on the latest release note however release notes don't always match up with current API version and based on this discussion the platform team would like the current API version to be displayed instead of the most current release note api version

This will make it easier for users to share links! Add user feedback in a tooltip that pops up after successful copy stating that the link was copied.

https://four51.slack.com/archives/G0ENQH3PF/p1582651313012000

Might be worth reviewing this doc for additional context:
https://docs.google.com/document/d/1W95hdlZJmWw2eQyCvBSEkX5XOUGOVT7zvoCmXFmvv2Y/edit#

The main page needs to be optimized at each view port. There is some weirdness happening with the main 3 cards, as well as the footer having too much margin.

Steps to recreate:

1. Navigate to https://oc-portal-test.azurewebsites.net/login and login
2. Navigate to https://oc-docs-test.azurewebsites.net/ and observe the call to action to "Login".

Expected results:
Should show your gravatar

Rather than create static images for @sm, @md, @lg: it might be better in the long run to try creating dynamic graphics using material-ui.

Per Todd's suggestionDate and author should be somewhere.

It actually looks like date is on the list page but would be nice to have it on the actual blog as well and "maybe" add author on list page? Although it looks like maybe the dog image would be replaced with an image of the author?

The other thing that would be nice to do is get more stock images for the list page, Would be cool if we could have them rotate in. We might also want a way to reference a custom image? maybe not.

Documentation for our documentation. Let's add some relevant READMEs to make it easy for people to contribute, both internal and external.

• CONTRIBUTING.MD - guidelines for how to write each type of doc, resources for good technical writing, examples for how to use syntax highlighting for code blocks, what kind of frontmatter each doc needs
• README.md with requirements, how to run locally, link to CONTRIBUTING.md, link to LICENCE.md
• Possibly doc templates for the different types of issues someone can create: docs, bugs. Example:
  

Anything else you can think of that might be helpful for someone to easily contribute.

Update the following packages to the latest version:
@material-ui/core - 4.8.2
@material-ui/icons - 4.5.1
@material-ui/styles - 4.8.2

Sort of started but no functionality attached to it yet.

At the bottom of the docs page there is a "Was this guide helpful" text along with a thumbs up and thumbs down button. We'll want to decide how this works, and where we'll output the data once we capture it.

On hover, expand the vertical navigation bar to expose full F51 OC logo + verbiage of what each menu item is. This will reduce people having to guess what each icon means.

We're always getting questions about impersonation and should really have a guide on it. There will be two parts to this:

1. Feature guide - high level overview catered to business user type that describes what impersonation is and why they might want to use it. Should link to guide (part 2)
2. Guide - Gets into detail, shows API calls, talks about impersonation configs and what the fields mean and are.

• Make links to portal release notes dynamic
  • Right now the version number in the link is a hard coded value that needs to get updated anytime a new release note is added. This could be easily forgotten and lead to linking to a stale release note.
• Make Portal release notes "landing page"
  • Right now navigating to /portal-release-notes displays the 404 page. Make it a page that redirects users to the most recent portal release note

They're that gross bright blue underline

We recieved a dropbox link to logos and design. If you pick up this task and don't have access, message me and I'll get you the link.

There will probs be a sister-task to update devcenter but it might be a good idea to lock it down on docs first and get feedback before continuing to that portion.

• Add a quick way to share
• Add the ability to make comments
• Add routes to other blogs
• Who wrote the article

Currently it's pretty bare bones:

Might be a purely design task unless there's other data points that could get fed into this template that might help with design?

Might be worth reviewing this doc for additional context:
https://docs.google.com/document/d/1W95hdlZJmWw2eQyCvBSEkX5XOUGOVT7zvoCmXFmvv2Y/edit#

Problem:

<Typography>
  <MDXRenderer>{post.mdx.body}</MDXRenderer>
</Typography>

This does not work. Material Theme Fonts are not getting passed into this element. Need to leverage MDXprovider to make sure rendered content gets the Material Styles.

Might be worth reviewing this doc for additional context:
https://docs.google.com/document/d/1W95hdlZJmWw2eQyCvBSEkX5XOUGOVT7zvoCmXFmvv2Y/edit#

Links within the homepage cards are not wrapping properly. Item names are jumping to the next column instead of wrapping below. See screenshot for context:

Could not recreate on Firefox, but this is confirmed on Mac/Windows Chrome.

Might be worth reviewing this doc for additional context:
https://docs.google.com/document/d/1W95hdlZJmWw2eQyCvBSEkX5XOUGOVT7zvoCmXFmvv2Y/edit#

When an endpoint is selected, display relevant information regarding that endpoint

• parameters
• request body
• responses
• path
• roles
• summary
• verb

Official gatsby guide for adding algolia search to a gatsby site.

The guide mentions optionally using DocSearch by algolia which is a completely free option but is a bit limited. The indexer runs every 24h and they don't index blogs. I think we want finer grained control so we'll probably want to go for the paid.

Currently it's pretty bare bones:

Might be worth checking out other tech blogs for inspiration. It would probably also be worth adding a summary and an image for each of the blogs, to be used on the list page, possibly on the detail page. Coordinate with design on images and image sizes as well as other data we might need/want to make this more appealing.

This section is currently missing. We'll need to update the design/layout on the homepage to accomodate for 4 section cards instead of 3.

• There should be some visual indicator that links are to external pages in the footer

The DocTemplate content sits within the frame in an arbitrary manner, and should be made to have proper padding/margin so it's not so unpredictable.

• The chainlink icon should be hidden in the main body, and only show on hover

• In the right nav, the chain link icon should be removed

• With both of these actions complete, the right nav will match the aesthetic of the main body content, which was the original goal.

Existing articles can be viewed here: https://ordercloud.io/category/development/

I'm not sure where they are sourced from but I would assume they are in markdown format.

Using the gatsby-plugin-google-analytics add the trackingId provided by marketing to the top of the head under the ordercloud.io cookieDomain

Let's clean it up for launch 🚀

Need to recreate this landing page: https://developer.ordercloud.io/community

The new docs structure talks about the though process behind each but the wording can probably be refined:
https://docs.google.com/document/d/1W95hdlZJmWw2eQyCvBSEkX5XOUGOVT7zvoCmXFmvv2Y/edit#

We need a home for links to:

• blog
• api reference
• sdks (better name?)

That is more prominent than where they are currently (in the footer). Originally we had a horizontal nav but went with the vertical nav to provide cohesiveness between the two sites.

Not sure if we want to have a horizontal nav and a vertical nav. Horizontal for doc specific links and vertical for links in common with portal. Then again I think we mentioned that might already be happening on mobile. Two horizontal navs on mobile?

In each docs page at the bottom there is a "Contribute to this doc" link that should open the file on github so users can make pull requests with updates. We've moved the docs into a different folder (they're now in content/ at the root). Might be worth seeing if we can make this a bit more dynamic so we never have to run into the same problem.

1. Organization Hierarchy
   • pretty low-fi mockup made by yours truly there. Please for the love of god replace it with something better
2. Catalog Hierarchy
   • graphic of a category tree
   • graphic of a category tree within a catalog
   • graphic of a category hierarchy within a catalog with product assignments. Products should live outside the catalog
3. Product Visibility
   • graphic representing a three point assignment between a product, a priceschedule and a usergroup
   • graphic representing an assignment between a usergroup, a product and price schedule and then the same product assigned to a different usergroup with a different price schedule.
   • Bonus: there's a "Product Visibility Cheat Sheet" at the bottom, any way we could spice this up a bit more? 🤔

Might be a good brogramming sesh to cook up the best way to represent these.

Design for 404 Not Found Page

Now that devcenter is part of the platform we'll need to have a release notes for them as well. Part of this task should be creating the initial release notes. Can probably piggy back off of this

https://docs.google.com/document/d/1Mki9VDrVYcb-myGh5S_FJL93PpRcV_sibiJrfZtqb3Y/edit

This would allow contributors to see what the output should look like for documentation only pages without having to manually build the project

Currently the following code will parse correctly in the project but will exclude anything after the second asterix via github. Kind of a bad example but it demonstrates that the content is being parsed differently than it is on github

`ValueExpression`: *"items.total(product.incategory('Bikes')) \*.15"*

App:

Github:

Laptop Monitor Size: 1280x720
Resolution: 1920 x 1080
Chrome Browser size: 1280 x 578

Steps to recreate: Go to ordercloud.io using Chrome Broswer and the page opens like this:

In the old documentation app we had the following section:

1. What is ordercloud
2. Getting started with ordercloud
3. Using the API console
4. Using the Dashboard

The homepage to documentation will have links to the first two guides #59 and the api console and dashboard will be consolidated into one unified devcenter so its a bit questionable whether we necessarily need and introduction to ordercloud.

At the same time, it might make it easier for developers to get to it if its listed in multiple places. If we do decide to have it as a section then create a new task for it as it will need to be listed on the homepage like we do for the others. This might also require additional design consideration to make it look nice.

clicking on a link from a long page doesn't seem to work

On some screen sizes/resolutions, the logo was peeking through the collapsed nav

We'll probs need to make one, doesn't look like it came in the stuff that got sent over. I suppose I wouldn't expect it to be there anyway.

For example navigating to the following link https://docs.ordercloud-qa.com/main-concepts/orders#statuses will land you a little below the actual section. Additionally clicking the anchor tag while on the page scrolls you down past the heade