Documentation Repository for Tanzu Application Platform (TAP)

Overview

This repo contains the content for Tanzu Application Platform docs, v0.1–v1.1

Branches

Product Names

There is a great variety of spellings and misspellings of product names. JD suggests the following list:

• Cloud Native Runtimes
• Application Accelerator
• Application Live View
• Tanzu Build Service (not Services)
• Tanzu Application Platform (not TAP)

But use the complete product name at first use:

• Cloud Native Runtimes for VMware Tanzu
• Application Accelerator for VMware Tanzu
• Application Live View for VMware Tanzu
• VMware Tanzu Build Service

Word List

Use this table to keep a running list of terms used and how they should be defined.

Placeholder List

Other style stuff

Top tips:

• Keep line lengths short, around 110 chars.
• Start each sentence on its own line. Markdown only creates new paragraphs after a blank line.
• We've changed our heading style to match the more modern style: sentence case not title case. So going forward, we only need to capitalize the first word in a title. E.g. "Other style stuff" instead of "Other Style Stuff."
• UI elements are bolded and the widget type not mentioned. For example, "Click on the NEXT STEPS button." is rewritten as "Click NEXT STEPS."

Autogenerated Docs

If a doc file is autogenerated, any direct edits are overwritten at the next autogeneration event. The files in these folders are autogenerated:

• scst-store/cli_docs

Troubleshooting Markdown

Creating a Pull Request

For instructions on how to create a pull request on a branch and instructions on how to create a pull request using a fork, see Creating a PR in the documentation team wiki.

Publishing Docs

v1.1 Staging docs:

• docworks is the main tool for managing docs used by writers.
• docsdash is a deployment UI which manages the promotion from staging to pre-prod to production. The process below describes how to upload our docs to staging, replacing the publication with the same version.

Prepare Markdown Files

• Markdown files live in this repo.
• Each page requires an entry in toc.md for the table of contents.
• Images should live in an images directory at the same level and linked with a relative link.

Create the ZIP File

Starting from the repo root, this will create a new docs.zip with no root folder and show its contents.

git pull ; rm *.zip ; zip -r tap-1-0 *

Upload the ZIP File to Docworks

• Go to https://docworks.vmware.com/md2docs/publish
• Fill in the fields exactly as below. Repeat this every time - the browser can help to remember form fields.
• Click on upload, and when prompted, enter your VMware AD password (for docsdash)
• If you see invalid path errors in the yellow box on the right there are broken links, but the site will still be published.
• If the toc.md is invalid then the site will not build, but there will be no indication that something is wrong.

Form Fields

Form fields for beta-1: VMwarePub.yaml Form fields for main (beta-2?): VMwarePub.yaml

In Docsdash

1. Wait about 1 minute for processing to complete after uploading.

2. Go to https://docsdash.vmware.com/deployment-stage

   There should be an entry with a blue link which says Documentation and points to staging.

Promoting to Pre-Prod and Prod

Prerequisite Needs additional privileges - reach out to Paige Calvert on the docs team #tanzu-docs or ask a writer to do this step for you.

1. Go to Staging publications in docsdash
   https://docsdash.vmware.com/deployment-stage

2. Select a publication (make sure it's the latest version)

3. Click "Deploy selected to Pre-Prod" and wait for the pop to turn green (refresh if necessary after about 10s)

4. Go to Pre-Prod list
   https://docsdash.vmware.com/deployment-pre-prod

5. Select a publication

6. Click "Sign off for Release"

7. Wait for your username to show up in the "Signed off by" column

8. Select the publication again

9. Click "Deploy selected to Prod"

Landing Page and Publications

General information about landing pages:

• Every product has a landing page (Not exactly true: every umbrella product, such as Tanzu Application Platform should have a landing page.)
• The landing page is a container for all the "publications" for a product. Our first publication will be our combined docs for our first Beta, including installation, and user docs.
• Typically there will be a new docs publication for each minor release but not each point release. This version number become part of the URL e.g. Our first release was version 0.1 (see form section above for the current release).
• Some products like Tanzu Kubernetes Grid publish separate release notes publications for each point release.
• For comparison see https://docs.vmware.com/en/VMware-Tanzu-Application-Catalog/index.html