Instructions to start writing a guide

Contributing a guide

Welcome to Open Liberty! In order to contribute a guide for Open Liberty, follow the steps in this README.

Step 1: Set up your computer.

• Install Git and become familiar with the Git triangular workflow.

• Install and know the basics of Maven or Gradle.

• Install a text editor with the AsciiDoc compiler plugin and learn the syntax of AsciiDoc.

Step 2 (Optional): Try some existing guides.

Use the guides on openliberty.io as examples.

If you’re not sure where to start, try the Creating a RESTful web service guide followed by the Injecting dependencies into microservices guide.

Step 3: Know the structure and style.

• Know your audience!

  • If the guide is introductory, explain the basic concepts of the technology. At the same time, try to avoid overwhelming the reader with too much information. If you’re not sure if you’ve included the correct amount of info, consider asking a new user to try your guide.

• Know the guide structure and the writing styles!

  • Take a look at the Guidelines for Structure and Styles.

Step 4: Create a new guide.

1. Clone the guides-template to your own workspace.

2. Develop your guide in your own workspace.

   • Develop code and write tests that are based on the project structure in the guides-template. To start, create your project in the finish directory. Make a simple application that demonstrates how to use your topic.

   • Copy the code from the finish directory to the start directory. Then, from the copy in the start directory, remove the code that you want the user to focus on.

   • Write a guide that follows the README.adoc template (APPENDIX A) in the guides-template repository. Introduce and explain the parts of code that you removed during the last step and tell the users where to copy and paste the code. Walk through how to build the finish directory, run the tests, and perform any other steps that users need to run your project on their own.

3. Before proceeding further, you should review the checklist.

4. Open a new issue in the guides-commons repository. Describe the topic you wrote, add a link to the repository that contains the complete draft of your guide, and the Open Liberty team will be notified.

5. You must sign the Individual Contributor License Agreement (CLA) in order to contribute. If you are writing the guide as part of your job, you might also want your employer to sign a Corporate Contributor License Agreement (CCLA). Instructions for how to sign and submit these agreements are provided in each document. You should send your signed CLA document (in PDF) to the email address cla@openliberty.io before you move on to the next step.

6. After the Open Liberty team approves your guide and obtains your signed CLA, they will create a draft guide repository in the Open Liberty Project on GitHub for you. Your new repository will be named as draft-guide-{projectid}. Then, you can open a pull request that contains your commits for the guide, and the team will be notified for review.

Step 5: The Open Liberty team will review your guide.

• You can see your feedback from the Issues section in your draft-guide-{projectid} repository when it’s ready.

• Follow up with the team’s review discussions.