How to create an Open Liberty guide
(Written in Markdown but needs converting to Asciidoc for ease of editing.)
This is a working draft that we're compiling to produce some nice, simple guidance to creating Open Liberty guides.
Published guides on openliberty.io are examples that can be referenced. Specifically, start with the REST guide.
That.
If the guide is introductory, make sure it explains the basic concepts of the technology. Test it out on someone who is new to the technology to make sure you haven't missed anything. Equally, don't include unnecessary information that doesn't help them to learn about the technology - that's just confusing and overwhelming.
The aim is to get the user doing something as quickly as possible. We do this in two ways:
- Provide a
startdirectory in the repository. This contains files that the user needs to run the sample code but aren't relevant to the topic of the guide. For example, the Maven guide provides all the Java class files in thestartdirectory because writing a Java class is not the focus of the guide. In other guides, the Mavenpom.xmlfile is provided in thestartdirectory because that isn't the focus of those guides. When the user has completed all the tasks in the guide text, their project should be identical to the project in thefinishproject. - Make sure the user can run some sample code as soon as possible. For example, in the REST guide, the user learns how to write tests for the app after having first run the basic code to see how it works.
Overall, the guide should help the user learn about the technology that is the focus of the guide. Make sure to explain why the code is written in a particular way (as long as it's relevant to the technology).
A template adoc for the guides is here - View the template in an editor or as raw text and see the comments for instructions and details.
Each guide is hosted in a separate GitHub repository. One of the first instructions in the guide is to do a git clone, so it is important that this is fast and focused on the guide being used. The repository is called guide-<short name for guide>. For example, guide-rest-intro. The repository contains 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 is written in AsciiDoc. When providing code snippets in the guide, import the relevant bits of source code in the finish folder (i.e. the completed sample). That means that any changes 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 line numbers. In general tags are a better approach since they are more resilient to code change.
Use Asciidoctor to build 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.
- 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) to ensure the guide works, and that the structure makes sense and is usable.
- Create a public repo on your own GitHub account to work on the draft guide
- Test your guide