Payara Server & Payara Micro Documentation

We’ve recently moved the documentation for Payara Server and Payara Micro from its original home in the GitHub project wiki. In doing so, we’ve altered the structure of the pages and introduced new ways to contribute through the GitBook platform.

Where Can I Find the Documentation?

The new documentation can be found within a GitBook at the following URL:
https://payara.gitbooks.io/payara-server/content/

The source code for the documentation is still hosted on GitHub so that issues can be created against the documentation and pull-requests can be made to contribute any documentation of your own.

Documentation Structure

The documentation is separated into 3 main sections, General Info (including details on the Payara project), Technical Documentation (concerning the usage of any new features we’ve added, including Payara Micro) and Appendices (any reference pages, currently just old release notes). Technical documentation is then further subdivided as follows:

• Core Documentation
  The reference documentation for GlassFish 4.0 is exhaustive and should contain everything needed to use features derived from the upstream GlassFish. There may sometimes, however, be a need to document things beyond this, and that is where the Core documentation comes in.
  
• Extended Documentation
  Any fix or new feature we add to the Payara Server or Micro codebase will be documented in this section. For example, we have documented the Request Tracing Service here.
  
• Payara Micro Documentation
  Originally a single page, Payara Micro documentation now has its own section. Since there is so much available, we have now separated each section into its own page to ease navigation.
  
• User Guides
  Since traditional documentation can sometimes be a bit dry and hard to consume, we have a “User Guides” section to walk through solutions to common tasks. For instance, upgrading to the latest version of Payara Server.

Changing Versions

Payara is versioned based on the year (2 digits) and the quarter (1 digit), such that the version released in 2016 quarter 3 would give a version number of 163, and the version released in 2017 quarter 1 would be numbered 171.

GitBooks supports multiple versions through simple URL manipulation. For example, adding a suffix of ../v/152/ to the root URL would take you to the documentation as it was at the version released in 2015, quarter 2. Viewing any other page will simply append the path after the version number – so, if you were to alter the version number to a previous version where the page did not exist, there would be a 404 error.

Consider the following:

• https://payara.gitbooks.io/payara-server/content/documentation/core-documentation/jacc.html
  The URL above leads to documentation on custom JACC providers. This page did not exist in version 153, so inserting that version to the URL will return a 404 error
   
• https://payara.gitbooks.io/payara-server/content/v/153/documentation/core-documentation/jacc.html
  The 404 error can be seen by visiting the above link

For convenience, we have added a plugin to easily switch between versions using a dropdown box. This gets around the issue of 404s by always redirecting to the Introduction page so, although your place may be lost, you will easily be able to get back to your original place. This version always defaults to the latest released version.

Raising Documentation Bugs

There are several ways of giving feedback on the documentation, the first being inline comments on the book itself. Hovering over each paragraph with the mouse will show an icon to begin a discussion. These discussions can be viewed from the gitbook.com site, however it is not advisable to raise bugs in this way since we are not notified of new discussions.

The better way of raising bugs is to raise an issue against the Payara-Server-Documentation repository on GitHub since this is the source of the book repository.

Contributing Changes

If you would like to contribute your own documentation, we will very gladly accept your contribution! To make it as easy as possible for your change or addition to be accepted (and properly attributed), we would ask that you follow these steps:

1. Fork the repository and make any changes in your own fork.
2. Before making a pull request, please rebase the next branch, and create a pull request to the next branch
3. Make sure you have signed the CLA, which can be found in the main Payara repository

Above all, we really value your feedback! As end-users of Payara Server and Payara Micro, the documentation we provide is for you, so please let us know of any additions or changes you would like to see.

{{cta(‘8a4f0637-38ea-458c-a66c-6307d6f21923’)}}