Skip to content

Latest commit

 

History

History
116 lines (91 loc) · 3.65 KB

style_guide.adoc

File metadata and controls

116 lines (91 loc) · 3.65 KB
Raw

Playbook Style Guide

Eric Sauer <[email protected]> :toc: macro :toc-title:

We welcome contribution and would like to do everything we can to encourage help from the community. Here are some guidelines to help you get started with contributing to the OpenShift Delivery Playbooks.

Starting a New Document

All playbook guides should begin with a top-level heading and, at minimum, the following metadata:

---
---
= Top Level Heading
Author Name <[email protected]>
:toc: macro
:toc-title:

toc::[]

Content Best Practices

Section Headers

Section headers should follow a sequential order, such that a Table of Contents can be properly generated, and Proper nesting should be followed at all times.

Good Example
= Top Header
== Section 1
== Section 2
=== Section 2.1
==== Section 2.1.1
=== Section 2.2
== Section 3
Bad Example
= Top Header
=== Section 1
=== Section 2
=== Section 2.1
===== Section 2.1.1
== Section 2.2
= Section 3

Links

Links should follow the following format:

link:/path/to/file{outfilesuffix}[Link Name]

The .adoc parameter should replace the file type and is there to handle the translation from '.adoc' to '.html' when we publish this content to our web front end.

Interlinking Playbook Guides

Whenever possible we try to have playbook guides refer to other playbook guides. Tying content together in a logical way helps us build up complete stories and solutions and even lead to other solutions.

When linking to other playbook guides, we like to take steps to make it as obvious as possible without ruining the flow of the doc. Here are some guidelines for formatting your links:

  1. Include the title of the guide in the link text. For example…​

    link:/playbooks/installation/installation{outfilesuffix}[OpenShift Enterprise 3 Installation]

    rather than

    link:/playbooks/installation/installation{outfilesuffix}[click here!]

  2. Provide some context as to why you are providing this link. For example…​

    The link:/playbooks/installation/load_balancing{outfilesuffix}[External Load Balancers Guide] provides an introduction to the strategies that can be employed within OpenShift

  3. Use a NOTE callout when there’s no natural flow.

    NOTE: The link:/playbooks/installation/load_balancing{outfilesuffix}[External Load Balancers Guide] provides an introduction to the strategies that can be employed within OpenShift

Include a "What’s Next?" section to encourage further reading

We like to conclude our documents with a "call to action" or something of that sort. Whenever applicable, think about ending your doc with a "What’s Next?" section with links out to further suggested playbooks guides, or other documents when a playbook guide doesn’t yet exist (if you think it SHOULD exist, please Open an Issue).

Requesting Feedback

If there are specific places where you’d like to request feedback or expansion from the community, we encourage you to call that out in your playbooks. Please use the following format:

.Feedback or Contribution Needed
****
This is a block where we would put a request for feedback or additional detail.
****

This will render as…​

Feedback or Contribution Needed

This is a block where we would put a request for feedback or additional detail.

Follow the Asciidoctor Style Recommendations

The above guidelines were specific to the OpenShift Delivery Playbooks. In addition, please keep the following AsciiDoc Recommended Practices in mind while writing guides.