search

kabanero-io / docs

Kabanero documentation. This repo will be archived soon.
https://kabanero.io/docs/
Apache License 2.0
7 stars 30 forks source link

Clean up / improve Docs area #176

Open SueChaplain opened 5 years ago

SueChaplain commented 5 years ago

Epic for issues relating to a clean up of the existing Docs area as a result of a doc meeting.

Content definition from our content architect:

To cover the following areas:

  1. Provide more info in the contributions guidelines to help users decide when to write a guide and when to create a doc page.
  2. Some topics were initially created in the Docs area to provide user information whilst Guides were developed. When the guides are available, some clean up work is required to remove duplicate content.
  3. The Reference section should contain only reference information, such as CLI or environment variables. Any doc in the Reference section that provides task-related information should be considered for moving to Guides (or moving into other sub-areas of Docs if an edge case).
  4. Reorder some content under Docs (if possible) to provide better flow of information.
  5. Provide some user journeys connecting users to the available guides.
SueChaplain commented 5 years ago

Hi @kaczyns - I wanted to reach out to you about one of the topics you authored for the Docs area - https://kabanero.io/docs/ref/general/app-deploy-namespace.html

I'm doing some rationalising of what we have to remove duplication, move content around under the structure, plus a bit of editing.

I believe that this topic is still current and valid but hoped you would be able to run your eye over it quickly to check. I have a few suggested edits that I want to make via a PR for your review, but wanted you to check for currency first.

Longer term, would you be supportive of moving this into a guide where we can walk the user through configuring a Kabanero instance ( basic config / how to use a different collection / how to configure alternative namespaces .. and anything else people see as a gap ... bring in the Operator maybe). Be interested in your views on this.

SueChaplain commented 5 years ago

Hi @kaczyns - as part of this work I wanted to move https://kabanero.io/docs/ref/general/collection-install.html to the Configuration section, alongside https://kabanero.io/docs/ref/general/app-deploy-namespace.html, as I think they are similar/work together. There is a PR https://github.com/kabanero-io/docs/pull/190 for this already, which I just add you as reviewer too.

kaczyns commented 5 years ago

@SueChaplain Hi Sue - that app-deploy-namespace topic is still current and valid. You can change it up any way that you want to. I think that a guide for this would be fine - I think that this page just represents one small piece of the puzzle that would be necessary for this flow, and I'm not really sure we have all of the pieces in place to have a cohesive guide here yet.

I will take a look at #190

jgawor commented 5 years ago

some of my comments on the docs:

SueChaplain commented 5 years ago

@jgawor

fix all Github references to GitHub

I fixed a lot but will do another sweep to make sure I got them all. We also have git -> Git, and trademarking issues. These things are best addressed when we have the doc updated and ready to go as a final sweep.

ensure that Installing Kabanero Foundation shows up first under Installation

There is no mechanism in the current build process to affect the ordering of subtopics (see #191). I think this is high priority, but not possible for 0.3.0.

There is likely to be a lot of movement around the Codewind topics as we have some new guides in development. There are a couple of topics that are inaccurate at the moment, so plan on removing those asap.

I don't think I'll get to your other request for 0.3.0, but this epic will live on into the next release.

mtamboli commented 5 years ago

I saw with our Java Microprofile guide (others will probably have similar issues) is that they commands are specific to a release. For example, appsody repo add kabanero https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml

I really do not want people to try old version if they are getting started. So the instructions should have a way to find the latest version of the collection and ask user to replace.

SueChaplain commented 5 years ago

@jgawor

separate https://kabanero.us-south.cf.test.appdomain.cloud/docs/ref/general/installing-dev-tools.html into two topics. one for elicse and one for vscode. otherwise, lots of replicated content. also add section (or a link) to how to configure it to use kabanero collections

See PR https://github.com/kabanero-io/docs/pull/202

Separating the topic into 2 will be better when we can control the subtopic order, otherwise the 2 will end up separating in the TOC. Instead I added some links into the topic to help users navigate between VS Code and Eclipse. I've also added links to the configuring topic, which also needed updating as it had a lot of inaccuracies in it.

I wanted to request a review from you on that PR but cannot add you in as a reviewer. I asked someone from the codewind team instead.

SueChaplain commented 4 years ago

@mtamboli

I saw with our Java Microprofile guide (others will probably have similar issues) is that they commands are specific to a release. For example, appsody repo add kabanero https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml

I really do not want people to try old version if they are getting started. So the instructions should have a way to find the latest version of the collection and ask user to replace.

I created #212 to see what there is across Docs / Guides and see how we might tackle this problem and reduce maintenance.