docs-tiledev/tile-documentation.html.md.erb at master · pvaramballypivot/docs-tiledev · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
---
title: Tile Documentation
owner: Services
---


This topic explains how to document your service tile for <%= vars.platform_name %>.


## <a id="overview"></a> Overview

When a VMware Tanzu service tile launches on [VMware Tanzu Network](https://network.pivotal.io), <%= vars.company_name %> publishes corresponding documentation at [https://docs.pivotal.io](https://docs.pivotal.io) under **Partner Services for VMware Tanzu**.

This documentation is formatted in [Markdown](https://daringfireball.net/projects/markdown/), stored in a GitHub repository that <%= vars.company_name %> creates, and is published with the [bookbinder](https://github.com/pivotal-cf/bookbinder) platform.


## <a id="template"></a> Partner Documentation Template

The [Partner Documentation Template](https://github.com/pivotal-cf/docs-partners-template) is a GitHub repository
that you can clone to create documentation for your service tile that follows the standard format for partner documentation.
The template works with the documentation publishing platform, [bookbinder](https://github.com/pivotal-cf/bookbinder).

Documentation content resides in the `/docs-content` folder of the repository, as skeleton pages with embedded prompts for content that you should fill in, approximately following the [content descriptions](#content) below.

See the repository [README.md](https://github.com/pivotal-cf/docs-partners-template/blob/master/README.md) for how to use the template with bookbinder to develop your documentation.


## <a id="content"></a> Documentation Content

While the specifics of your documentation will vary depending on the product, we have provided a basic blueprint below. At minimum, documentation should include #1 (Overview) and #2 (Installing/Configuring).

For a good example of a partner service document, see the [JFrog Artifactory documentation](https://docs.pivotal.io/jfrog/index.html).

If you have questions or want to collaborate on drafting the documentation, feel free to hop on our Slack channel #tanzu-docs. We’re always happy to help!

### <a id="index"></a> Index/Landing Page

General overview of Partner Product. What does it do? What are its features?

Key Features

- Feature one
- Feature two
- Feature three

#### <a id='partner-service-broker'></a> Partner Service Broker

A Service Broker allows Cloud Foundry applications to bind to services and consume the services easily from App Manager UI or command line. The Partner Service Broker will enable you to use one or more Partner accounts and is deployed as a Java Application on Cloud Foundry. The Broker exposes the Partner service on the Cloud Foundry Marketplace and allows users to directly create a service instance and bind it to their applications either from the Apps Manager Console or from the command line.

The Tile for Partner installs the Partner Service Broker as an application and registers it as a Service Broker on Cloud Foundry and exposes its service plans on the Marketplace.  This makes the installation and subsequent use of Partner on your Cloud Foundry applications simple and easy.

If a trial license available, customers interested in using Partner can obtain a 60 day free trial license from edit link here.

#### <a id='product snapshot'></a> Product Snapshot

Current Partner Tile for VMware Tanzu Details:

- Version:
- Release Date:
- Software components versions: Partner product version
- Compatible Ops Manager Version(s): 2.10.x and 2.9.x
- Compatible TAS for VMs Version(s): 2.10.x and 2.9.x

#### <a id='requirements'></a> Requirements (or Prerequisites, Packaging Dependencies for Offline Buildpacks, etc.)

Provide any general or specific requirements here. A general requirement might be something like, "An AppDynamics account." A specific requirement might be something like, "Packaging Dependencies for Offline Buildpacks."

#### <a id='limitations'></a> Limitations

Any known limitations.

#### <a id='feedback'></a> Feedback

Please provide any bugs, feature requests, or questions to the <%= vars.platform_name %> Feedback list.

### <a id="install"></a> Installing/Configuring the Tile

This topic provides instructions for how to install and configure the tile. Typically this includes procedures for how to download the tile from VMware Tanzu Network, install it on Ops Manager, configure the tile, and do any required third-party configuration. Screenshots should be provided where necessary. Consult the following format:

#### <a id='install-with-om'></a> Install Using Ops Manager

- Download the product file from VMware Tanzu Network.
- Upload the product file to your Ops Manager installation.
- Click Add next to the uploaded product description in the Ops Manager Available Products view to add this product to your staging area.
- Click the newly added tile to review any configurable options.
- Click **Review Pending Changes**, then **Apply Changes** to install the service.

#### <a id='upgrading'></a> Upgrading to the Latest Version

If there are any specific instructions for upgrading the tile, you can include those here. If the procedures are complicated, create a new Upgrading topic.

#### <a id='configuring'></a> Configuring the Partner Tile

Add snapshots for each step when possible or add details as required.

- Log in to Ops Manager.
- Click **Import a Product** and import the Partner Tile.
- Select the Partner option.
- Click **Add** on the Partner Tile.
- Select the Partner Tile.
- Configure the Partner Tile.
- Apply your changes.

On completion of Partner Tile install, check Services Marketplace in Apps Manager:

- View Partner Service Plans.
- Bind the Partner Service to an Application.
- Check the service or dashboard for the partner for more data.

#### <a id='other-configs'></a> Other Configurations/Third-Party Configurations

Provide information for specific configurations like configuring for HTTP proxy, or doing any necessary configurations on a third-party service portal.

### <a id="using"></a> Using the Tile

This topic provides instructions for how to use the tile. Typically this includes procedures for how to perform the different functions offered by the service. Screenshots should be provided where necessary. You can also include information about Architecture here if necessary.

### <a id="troubleshooting"></a> Troubleshooting

This topic provides troubleshooting information for known errors, following the Symptom/Explanation format used here: [https://docs.pivotal.io/p-identity/okta/troubleshooting.html](https://docs.pivotal.io/p-identity/okta/troubleshooting.html)

### <a id="release-notes"></a> Release Notes

Include the release notes as the final topic, following the format in the [docs-partners-template](https://github.com/pivotal-cf/docs-partners-template/blob/master/docs-content/release-notes.html.md.erb).