Improve user guide

[cdrage]

Discussion for improving the user-guide.

[mishaone]

Findings

I perused the docs, primarily the User Guide (UG) part and the Installation Guide (IG) part. My expectation was that the IG would tell me what I need to install and the UG would tell me what I can do with Kompose, possibly walk me through a common use case for the tool, etc.

I remained confused for a while because while the IG is as expected, the UG seemed like a reference document since it lists all the commands available for Kubernetes and OpenShift but not much about what I'm doing or why.

I unexpectedly found the information I was looking for in the Introduction section. What I expected to find here was an overview of what Kompose is and what one would use it for. Instead, it has a concise and clear (and I assume, most common) use case for the tool.

Workflow

After reviewing all the information, I came up with the following basic workflow for a common use case:

1. Configure/customize your docker-compose.yml file:
   1. Use Kompose-specific labels to your yml file to define the service's behavior when converted, specifically kompose.service.type and kompose.service.expose.
   2. To create pods without controllers, use restart in the yml file to define this. Valid options include "", always, on-failure, and no.
2. Deploy your application in one of two ways:
   1. Run kompose up (with options for Kubernetes or OpenShift) in the same directory as the yaml file. The UI has a build key that does the same thing.
   2. Run kompose convert and then kubectl create -f to convert V1, V2, and V3 Docker Compose filed into Kubernetes or OpenShift objects and then deploy them). There are also a variety of additional parameters (-j, -c, --daemon-set, --replication-controller) for generating JSON files, Helm charts, and Deployment objects.
3. View the deployed service in one of two ways:
   1. If you are already using minikube for development, run minikube service frontend.
   2. If you are not using minikube, look up your service's IP address using kubectl describe svc frontend and then "curl ".
4. Remove the deployment and reclaim resources using kompose down.

Does this seem about right to you?

Proposed Changes

I would recommend a restructure to make the content flow in a more intuitive way for users, as well as a general edit to fix up some phrasing that is either unclear, informal, or at times a bit convoluted.

For the restructure, I would recommend:

General:

• Confirming a primary workflow that is common to most users, as above, and then fleshing out the steps.
• Outline the general workflow and explain what each step does, then flesh out the details of each step in subsequent sections. These sections provide details and alternative paths for each step.

Landing Page:

• Change the landing page (http://kompose.io/) from the introduction to just a quick explanation of what the tool is and what you would use it for. As it stands, the information there is useful, certainly, but a bit overwhelming since we don't know which part of the menu (left side of page) we are at yet or what the information being presented is.
• Add a very high level outline of the identified workflow here so that the user is eased into what they will be doing, or click through directly to a step.

User Guide/Getting Started Guide:

• The User Guide can probably remain a more reference based document, much like it is now.
• Add a Getting Started guide or something similarly named so that new users know exactly where to go to start and get a walkthrough.

[mishaone]

@cdrage These are my initial thoughts. Please let me know what you think and we can discuss it further.

[cdrage]

@mishaone Thank you so much! I will go through this and make some updates / notes in regards to the site.

Have you looked at http://kedgeproject.org ? We've included an "introduction" page to the index, is this similar to your suggestion of having the landing page updated to reflect an explanation of the tool as well as what people would use it for?

[mishaone]

Hi @cdrage,

Happy to help! The Kedge Project site looks great. That's precisely the sort of thing I meant.

Would you like me to create issues to track these items or do you prefer to track them yourself somewhere?

[cdrage]

@mishaone I'll split off the issues into separate tracking cards / issues. Thanks again for the feedback!

[cdrage]

TODOS:

General:

• Confirming a primary workflow that is common to most users, as above, and then fleshing out the steps.
• Outline the general workflow and explain what each step does, then flesh out the details of each step in subsequent sections. These sections provide details and alternative paths for each step.

Landing Page:

• Change the landing page (http://kompose.io/) from the introduction to just a quick explanation of what the tool is and what you would use it for. As it stands, the information there is useful, certainly, but a bit overwhelming since we don't know which part of the menu (left side of page) we are at yet or what the information being presented is.
• Add a very high level outline of the identified workflow here so that the user is eased into what they will be doing, or click through directly to a step.

User Guide/Getting Started Guide:

• The User Guide can probably remain a more reference based document, much like it is now.
• Add a Getting Started guide or something similarly named so that new users know exactly where to go to start and get a walkthrough.

OTHER / ADDITIONALLY ADDED:

• Highlighting added Add highlighting for menus + add slack/releases/github links #831

[cdrage]

Most, if not, all of the tasks above have been completed. Thanks again for @mishaone for the feedback! 👍