Getting Started

Create a new private repository at https://github.com/pcf-guides. Each document lives in its own repository at GitHub under the pcf-guides organization. This step requires help from an owner on the pcf-guides organization. Name the repo draft-gs-<name of guide>.

The "draft" part of the title prevents the guide from being published to the Cosmos web site. The Cosmos web site is designed to look for all gs-* repositories and publish those to the guides section. All pat-* repos are published under /patterns, and all ref-* repositories are published under /references. By initially naming the repository with a "draft-" prefix, Cosmos will ignore the repository.

When you're ready for the guide to be published, you'll rename the repository, dropping the "draft-" prefix.

Configure description

The description field in the repository is used on the Cosmos web site to display the title and description for each guide. Edit the description to include the title and description separated by a double colon “::”. This is used by the Cosmos web site to parse the two values. Enter the Cosmos URL for the guide in the repository website field. Do not include “draft”.

Description format:

<title> :: <description>

URL:

http://cosmos-dev.cfapps.io/guides/gs/service-registry/

Add collaborators

Add committers, administrators, and viewers teams to the repository collaborators.

Adding content

Generally, a getting started guide has three main artifacts:

• A README.adoc file containing the guide's manuscript.
• An initial/ directory containing the initial state of the project before working through the steps in the guide. Often, this is just a basic Maven/Gradle project structure with a minimal build specification.
• A complete/ directory containing the project in its completed state. This should reflect the state of the project after the reader has performed the steps in the guide.

This project contains a sample guide along with the initial/ and complete/ projects. You may mimic its structure when authoring your guide. Or, for a quick start, you can clone this project, change the remote repository URL, and push it to the new repository:

$ git clone https://github.com/pcf-guides/getting-started-guides.git draft-gs-<name of guide>
$ cd draft-gs-<name of guide>
$ git remote set-url origin https://github.com/<your github id>/draft-gs-<name of guide>
$ git push origin master

Now you have a guide repository with the essential elements of a getting started guide. Edit/replace those with content the communicates the subject of the guide you're authoring.

For patterns, and references, use the same practices, but drop the need for any code (initial or complete).