OKD user experience

[Brian Innes]

Hello, at the Docs working group session yesterday I raised the issue of ease of use of the OKD.io site.  As a new OKD user and community member the site can be quite confusing to navigate.

I believe this issue will be raised to the main working group session, so I thought I’d give a little extra context in preparation for that meeting.

In my mind this site needs to support 2 different communities.  The OKD user base and the community of volunteers that want to support and improve OKD.  The OKD.io site mix up these communities, which I think adds confusion.

Currently the main navigation on the site contains:

• What is OKD (this is the site main page, but navigates to a lower section)
  
• Installation (this takes you to a git repo : https://github.com/openshift/okd/.  This repo contains Guides, troubleshooting, FAQ, Known Issues and the Contributing guide)
  
• Documentation (this is the OpenShift documentation modified for OKD)
  
• Blog
  
• Community (this is the site main page, but navigates to a lower section)
  
• Recipes (this takes you to a page with 2 recipes, for disconnected installs of OpenData Hub and Rook Ceph)
  
• Guides (this currently takes you to a git repo : https://github.com/elmiko/okd-deployment-configuration-guides#okd-deployment-configuration-guides, however, there is a PR (https://github.com/openshift-cs/okd.io/pull/196) to add this content on the OKD.io site
  
• Link to Git repo (same link as the Installation navigation item)
  
• Link to slack channel

Items to consider/discuss

• It is quite frustrating when so many of the navigation links lead back to the content already viewed
  
• What should live in the OKD git repo and what should be on OKD.io?  There is similar, but different, content in both places as well as cross linking.  Maybe OKD.io becomes the place for user content and the git repo the place for the working group content?
  
• Personally I’m unclear about the difference between the 2 guide sections (on site and in repo) and the recipes - should these all be combined into a single section?
  
• It is unclear where an OKD user goes for support.  This information is currently in the community section, but I think we need a Support navigation item to provide the information about how to interact with the project as a user looking for assistance.  The community section then has a clear single purpose as the landing place for those volunteering to join the working group.
  
• On the subject of support there appears to be numerous places that the community and users interact:
  

• Slack 

• Google group 

• Git repo issues 

• Git repo discussion section 

• Mailing list 

• SlackOverflow

There is little guidance on how these channels should be used.  I see that some people looking for help are posting in multiple places, suggesting they are also unclear.  We should have clarity on the purpose for each channel - E.g. should this post be in the Git discussion section or in the google group?  

• Under the main navigation there are 3 buttons:
  

• Get Started (link to the same git repo as the Installation link in main navigation)
  
• Releases (link to the releases page)
  
• Join us on Slack (same link as icon in main navigation)

Perhaps the Get started and Releases links aren’t the best places to send a new user?  Ideally we want a positioning page, discussing the various install options, linking to the guides/recipes and the OKD documentation to help new users onboard.

Clearly there are some decisions to be made by the working group regarding the site, but if there is interest I’m happy to join a sub-group to help improve the OKD.io experience.