Skip to content

How to create an Open Liberty guide

Jump to bottom
YK Chang edited this page Oct 25, 2017 · 15 revisions

This is a working draft that we're compiling to produce some nice, simple guidance to creating Open Liberty guides. This guidance should clearly explain:

  • The scope of an Open Liberty guide.
    • What to include and what to leave out.
    • What to focus on.
  • Structure a guide.
  • Sample code in the repository that accompanies the guide.

It should also provide links to extra info in case the contributor needs it, eg:

  • Using Asciidoc to write the guide.
  • Running a local build of your guide to see how it looks.
  • Creating a repo with folder/file structure and example repo to follow.

Exemplar Guide

Published guides on openliberty.io are examples that can be referenced.

Guide Template

The template for the Guide asciidoc can be downloaded from here: TBD

How Guides will be written

Each Guide will be hosted in a separate GitHub repository. One of the first instructions in the guide will be to do a git clone, so it is important that this is fast and focused on the guide being used. The repository will be called guide-. For example, guide-rest. The repository will contain a start folder, a finish folder and a README.adoc. The start folder is the starting point for running through the guide. That folder, plus the instructions should result in the code in the finish folder.

The guide shall be written in ASCIIdoc. When source code is being imported the source code must be included from the finish folder. That means a change to the application source will be reflected in the build webpage, no need to copy and paste. ASCIIdoc includes are very powerful and can select based on tags or lines. In general tags are a better approach since they are more resilient to code change.

Use of asciidoctor is recommended for building the HTML locally, this is what the website will use and it produces good error messages. Atom (and other editors) has a live ASCIIdoc preview view although at this time it didn't support all the syntax that asciidoctor 1.5.6 does.

ASCIIDoc Syntax Quick Guide: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ ASCIIDoc User Guide: http://asciidoctor.org/docs/user-manual/#include-directive

Review Process

  • Guide and related assets are created
  • Review by a committer for content and structure
  • Review by SME for technical accuracy and feedback
  • Review and editing for language
  • Review and walkthrough by a non-SME (e.g. new user, less experienced person)

Clone this wiki locally