Update of okd.io site

[binnes]

At the docs working group 27 July 2021, we discussed a post I made on the google forum about the okd.io site:

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  /  Mailing list 
- Git repo issues 
- Git repo discussion section 
- 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.

During the working group meeting we also discussed :

• the middleman technology used to generate the okd.io site and alternate technologies to make the site easier to contribute to and maintain with the goal of creating a beta site for evaluation and feedback
• Additional content needed, such as more technical content to help new community members 'get up to speed' and become contributors
• reorganising the existing content to have distinct sections for the end user community and the working group / contributor community

I was also asked to start this discussion thread, copying in the original post so we can discuss the okd.io site here

[vrutkovs]

Maybe OKD.io becomes the place for user content and the git repo the place for the working group content?

In order to update OKD.io content we need reviews and approvals, its probably not a great place for user-generated content - we don't want to be gatekeeping it.
For user group content we also have https://github.com/openshift/community, which is convenient place to organize meeting content aside from guides / discussions.

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?

Its probably a good idea to use OKD repo Guides as a staging - and eventually promote guides to okd.io?

It is unclear where an OKD user goes for support

I'd rather explicitly state the there is NO SUPPORT FOR OKD, but here are a list of discussion places where you might be helped with

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?

There is no way to enforce that anyway - people would be crossposting anyway, we can however respond only once in the place we prefer, thus making a particular channel for communication preferable depending on the context - i.e. failed installation/upgrades are best answered in Github Discussions (has threads, can be unsubscribed from, marked as answered), Slack can serve as quick Q&A place etc.

[binnes]

I agree there needs to be controls in place. I see okd.io is something that the working group members would update rather than the wider community, and like now changes would be made via a pull request that needs to be approved.

Hopefully having more detailed guidance on the purpose of each resource and being specific about where end users should go to connect with other community members to ask for assistance will avoid the cross posting, and where It happens we will have a page to send them, detailing the use of each resource and community etiquette

[binnes]

I created a proof of technology site using github pages : https://binnes.github.io/okd-io/. This is not what I think the final design should be, rather a platform for us to have further discussion to determine what we want on okd.io and what technology should underpin the site. I’ve put a little content into the site, but not moved everything across. I’ve left the home page pretty much as it is now, again this is probably not what we want to end up with, but shows a possible integration of the home page and the docs pages. I’ve put some thoughts on what we need to do next here : https://binnes.github.io/okd-io/okd-io/.

I've asked that the proof of concept site be on the agenda for the next docs working group session

[vrutkovs]

From engineering perspective this looks good. I think we can slowly move guides / tech info to okd.io instead of markdowns in /okd repo. This way we'll ensure guides are curated - and we can use this repo as discussion point / staging.