Review documentation

[wtrocki]

We need guides to define better documentation for:

• Kubernetes installation
• How our controllers behave (deletion etc.)
• SBO documentation - what is the end result of this operator - not clear right now
• Review documentation for any updates that we made to resources (metadata etc.) that weren't reflected in the docs

[secondsun]

Action : Break this into issues for each bullet point.

[secondsun]

Include documentation for setting the production/stage environemnt variables. This replaces #112

[secondsun]

WRT connecting to SBO

link to https://github.com/redhat-developer/app-services-cli/blob/main/docs/commands/rhoas_cluster_connect.adoc and the plugin which will be part of openshift 4.8 and give a few sentences to describe that this is the source of truth for those tools

[secondsun]

Add guides repo @wtrocki will link these on this issue

[secondsun]

I've been stuck on this a while and haven't made progress, unassigning to regroup.

[wtrocki]

@secondsun but who will do it? This was the only item you have been assigned on for couple weeks.
This seems critical from point of view of the operator and currently blocking pre summit epic from being closed.

[secondsun]

I don't know, we can get someone from docs. I'm just not sure what to do with this/where to take it/how to close it. I feel like the docs operator side are done enough for where we are and this can just be closed.

[wtrocki]

I have shared document that can be used as source and literally copy pasted.
This was assigned to you for number of weeks. Let's close that issue please as our operator is now public facing.
I'm working outside operator right now with CLI and Plugin work that needs to be refined.
Have no capacity - this became a critical element and it could be literally copy-paste from existing resources we shared.

CC @pmuir

[secondsun]

If you have a doc that can be literally copied and pasted then the docs are done, copy paste it, and be done.

[pmuir]

@jciroli-rh FYI - this relates to the docs.

I think the next step is to have a writer review what we've got, and see what is missing.

[pmuir]

Assigning to @jciroli-rh for next steps.

[jciroli-rh]

Assigning to @jbyrne-redhat, who is looking at operator/binding deliverables now.

[jbyrne-redhat]

@pmuir @wtrocki @secondsun - Is this the same documentation review task that we're tracking in https://issues.redhat.com/browse/MAKDOC-148? That is, the Operator documentation found here?

[jbyrne-redhat]

@pmuir @wtrocki @secondsun Also, can you say more about associated user/job stories for this documentation? The sections on Custom Resources, controllers, and API mocks get into a lot of underlying detail for the RHOAS Operator. I wondered how much of this we would want to expose in our upstream and downstream guides.

[wtrocki]

We want to have some user stories. Those would be typically technical details used to integrate with operator in cli and openshift and not really part of the end user doc.

The only part that is valid there is installation but needs more work.

We are missing following stories:

• What operator does
• How to use it
  • How to use it CLI
  • How to use it OpenShift
• What is service binding
• Service Binding Service reference

[wtrocki]

As for the jira - This is upstream github issue created to actually write content. We do duplicate issues as community do not have access to jira

[jbyrne-redhat]

Thanks for your replies, @wtrocki - they helped to clarify things.

With regards to the missing user stories you describe, I have begun work on defining an outline for a dedicated service binding guide. That guide will address all of the user stories you've outlined above. It helps to know that the Operator documentation developed via this issue is not regarded as end-user doc.

[wtrocki]

Also woth checking guides we already have for service binding in guides repo and in this repo as well:

https://github.com/redhat-developer/app-services-operator/tree/main/olm/quickstarts

[jbyrne-redhat]

For the documentation review requested in this issue, I believe the scope is confined to the various Asciidoc files found here: https://github.com/redhat-developer/app-services-operator/tree/main/docs. These are:

• Installation of RHOAS Operator
• RHOAS Operator Custom Resources
• RHOAS Custom Resource Lifecycles
• API Mocks

I will review each of these in turn and open a PR against each one.

[jbyrne-redhat]

PR for review of Operator installation procedure: #221

[wtrocki]

Good documentation for similar concepts that can be used as influence

https://aws.amazon.com/partners/servicebroker/
https://github.com/GoogleCloudPlatform/gcp-service-broker
https://crossplane.io/docs/v1.2/concepts/overview.html

[jbyrne-redhat]

Thanks, @wtrocki. I'll review those resources for our end-user documentation.

[jbyrne-redhat]

For now, however, I'll continue to focus this issue on review of our developer/contributor documentation.

[jbyrne-redhat]

PR for review of the Custom Resource controllers documentation: #222

[jbyrne-redhat]

PR for review of the Custom Resources documentation: #225

[jbyrne-redhat]

PR for review of API mocks documentation: #227

[wtrocki]

FYI. We were explicitly asked to provide documentation for OpenShift UI and operator for OpenShift support team.
Requirement is to provide information about Console client. What it does etc.

[jbyrne-redhat]

FYI. We were explicitly asked to provide documentation for OpenShift UI and operator for OpenShift support team.
Requirement is to provide information about Console client. What it does etc.

ACK, @wtrocki. Are there new issues for development/review of that additional documentation?

I believe #158 is now complete according to its original scope - all of our existing documentation has been reviewed and updated.

[wtrocki]

Amazing point. Let's close this issue.

I have created separate issue based on the comment above.
User documentation will be separate concern:
#228