Make /docs look presentable

[alohr51]

Right now the /docs page could use some kabanero coloring and some realignment of buttons to look presentable.

@mdenby can you give us a quick mockup with what we can do with https://kabanero.us-south.cf.test.appdomain.cloud/docs/ ? maybe something simple to start. You can ignore the guides button for now since we don't have any

[bschrammIBM]

The doc area will need to be redesigned to be similar to the Open Liberty Guides and Reference structure. The plan is to have 1 guide ready by end of August. It is: Guide 1: Using the Eclipse MicroProfile Collection including the serverless deployment option (audience=Jane)

Following are other guides/info: Guide 2: Kabanero Installation (based on script-based installation) (Todd) Guide 3: CP4Apps Installation (Todd) Guide 4: Working with Collections (Champ) Guide 5: Working with Pipelines – Tekton (Champ) Guide 6: Application Modernization, includes Transformation Advisor (Champ) Guide 7: Working with Codewind (Jane) Guide 8: Development Process Overview (Jane) Reference: Collection Management CLI (Champ)

[mdenby]

@alohr51 Here are the updated Docs page designs. I've also attached the redline here.

Docs redlines.zip

1. Add 'Resources' in the navigation with a dropdown. For now it can just have one dropdown for 'Docs'. Later when we have guides we can add another dropdown for 'Guides'. The rollover state is red. The dropdown text is 14pt Source Sans Pro SemiBold.

2. The sidebar menu has '+' to open and '-' to close, if no subcategories then no icon. I don't know what the categories are--though we would like an Intro to Kabanero. @bschrammIBM we can chat about it--or if you have thoughts about how to organize the categories.

Sidebar text: 16pt Source Sans Pro SemiBold Page title: 28pt Source Sans Pro Bold Body text: 16pt Source Sans Pro Regular Subtitle text: 20pt Source Sans Pro SemiBold

3. This shows the sidebar menu open.

Subcategory text: 16pt Source Sans Pro Regular Active/Hover for the subcategory: 16pt Source Sans Pro Semibold

[bschrammIBM]

Adding thoughts here about /docs:

• If we use Markdown for the doc pages, there is the possibility to reuse the same topics on https://cloud.ibm.com/docs.
• Can we update contributing.md for the /docs area for the new design - there are writers who want to contribute. Need to add them the the repo too so they can generate PRs.
• New requirement from Alan: Docs are available only to a user based on the collections that are installed. (not sure how to do this as you would need to be authenticated with a username/password - must be for AppHub on OKD)
• Translation issue
• ability to generate a PDF needed?
• Draft outline for docs that will be posted on kabanero.io: Installation instructions: IDE (Codewind) (Jane) CLI (Appsody) (Jane) Management CLI (Champ) Kab Foundation (Todd) Guides: • Kabanero Overview • Working with the Microprofile Collection • Others to come after MVP

Reference: • Management CLI reference • Appsody CLI Reference (or will this stay on the Appsody site?)

Links to OpenSource docs (IBM-affiliated): • Codewind https://www.eclipse.org/codewind/docindex.html • Appsody https://appsody.dev • Razee https://razee.io Links to OpenSource docs (public): • https://tekton.dev/ • https://istio.io/ • https://knative.dev/

[mdenby]

Posting a new sidebar, but Barbara will update the categories officially in Slack or here.

[SueChaplain]

@mdenby Question to help me understand the plan please:

• kabanerio.io currently doesn't have a direct connection to the /docs area
• is the header in this new design a replacement for the kabanero-io site? If so, what happens to the Try It link? Or maybe docs is a separate site?

[alohr51]

@SueChaplain Right, there is no direct link to /doc (which is currently a landing page we will be getting rid of).

The plan is when you go to /docs it goes to https://kabanero.io/docs/ref/general/ instead.

The header in this design will replace the one on the kabanero.io site. There is a whole other design for the Getting Started that will replace Try-It and be updated in issue https://github.com/kabanero-io/kabanero-website/issues/88 once its ready. So for now we will be adding the Resources tab (includes a dropdown with a link to the new /docs) until the Getting Started section is ready.

[bschrammIBM]

Based on the discussion today, we won't have any doc categories or subdirectories. We will have Guides and Reference (we are using the OL design). All procedural content, conceptual, and architectural documentation will be distributed as a guide. Each guide will be in a unique repo. The current reference content consists of the Management CLI. So the contributing.md should discuss how to create and submit a Guide. Doubtful that users will submit reference text. The getting started pages will provide installation and a few procedures.