This short guide will help you if you want to make a contribution to the Eclipse OpenJ9 user documentation.
Note: There is a short video presentation explaining the process for contributing to the OpenJ9 documentation. (Save and open the .zip file in the /process directory to view the .mp4 video.) You can also view the PowerPoint presentation used in that video. (Either save the file to view locally, or click "View raw".)
-
If you don't want to contribute directly by modifying the documentation yourself, but you have a suggestion or want to report an error, please raise an issue in this repository.
The following templates are available to help you provide the correct information for someone else to handle any changes:
-
If you want to contribute to the documentation, we recommend that you install a local test environment for editing and previewing your changes. The user documentation is authored in Markdown and built into HTML using Mkdocs, with a mkdocs-material theme.
To get started, follow the guidance in the following sections:
- Setting up a local MkDocs environment
- Editing the documentation
- - Documentation structure
- - Style guidelines
- - Writing tips
- - Which platform?
- - Which OpenJDK version?
- - Trademarks
- - Using images
- - Referencing non-Markdown pages
- - Accessibility
- Testing your changes locally
- Submitting a contribution
- Accepting contributions
Basic pre-requisites:
- Git
- Python 3
- Pip 9.0.1
- a Markdown editor (Atom, for example)
Use pip to install the other components, reusing the requirements.txt file in the /buildenv directory of the repository to ensure that you are mirroring build levels:
pip install -r requirements.txt
Next:
- Fork the repository: https://github.com/eclipse-openj9/openj9-docs
- Clone the repository:
git clone [email protected]:<your_github_account>/openj9-docs.git
If you are working on a Windows™ system, set the following Git configuration, which allows you to edit with Windows line endings (CRLF), but converts to Unix-style endings (LF) when you push changes:
git config --global core.autocrlf true
The source files are written in GitHub-flavoured Markdown format. We recommend using Atom for editing, which includes a markdown preview package so that you can check your changes as you write. Here is a 3 minute read on Mastering markdown.
For improved structure and styling options, a Markdown extension for definition lists is also included. This simple extension allows you to create a title and indented definition by using a semi-colon (:). For example:
Title
: definition
All files in the ROOT folder of this repository are concerned with the structure, build, and automation of the documentation hosting solution.
The key configuration file for the documentation is the /mkdocs.yml file, which controls the following aspects:
- website and repository addresses
- MKdocs theme and customisation values
- structure and content, under the
pages:section
Under pages: in the .yml file, topics are added and indented to reflect their position in the table of contents. Care must be taken to preserve the indentation when making changes to this file.
If you want to add a new file, see Document files about file naming, and follow the existing structure and layout when you add a reference to it in the .yml file.
Insert new options in the appropriate position in the list, which is typically arranged in alphabetical order within a section.
Note: From version 1.0 of MkDocs, the pages: section is renamed to nav:
Documentation content is contained in the following directories:
- All Markdown files are in the
/docsfolder. - All diagrams used in content are in the
/docs/crfolder.
New file names should follow the existing naming convention. They must be in lowercase. They typically omit punctuation and other symbols present in the full option title. Topics that form part of a group might have a distinguishing prefix.
Some examples:
| Topic / option name | File name |
|---|---|
| -Dcom.ibm.lang.management.verbose | dcomibmlangmanagementverbose.md |
| Java stack (jstack) tool | tool_jstack.md |
| -Xconcurrentbackground | xconcurrentbackground.md |
| -XX:[+|-]ShareAnonymousClasses | xxshareanonymousclasses.md |
For consistency across the user documentation, there are a few style guidelines that you should follow. These are not set in stone, so if you have any suggestions or concerns, open up a discussion in the Slack channel. If you haven't done so already, join the channel.
Generally, follow the style and structure of existing topics. If you are creating a new topic, you might find it helpful to copy a similar existing topic and modify it. (Don't forget to modify the file name in the footer!)
However you create a new topic, you must ensure that the header comment with copyright and license information is copied exactly as it is from an existing topic. Do not change either of the copyright dates, even for a new topic; the dates refer to the complete documentation set, not to individual files and so should be the same in all topics.
Make your contributions valuable to all users, including those who have English as a second language. Ensure that you write clearly and precisely. For example:
- Use simple language.
- Avoid needless words.
- Use short sentences but avoid using too many sentence fragments.
- Be direct: use active voice and present tense.
- Avoid ambiguity: what exactly does the "this" you wrote refer to?
- Use second person ("you" and "your") to better engage the audience.
- Don't overuse punctuation for effect, especially avoid making everything either a question or an exclamation!!
- Make humor universal and timeless, but in technical documentation, humor is best avoided.
Although OpenJ9 supports a number of platforms and architectures, there might be different configuration and tuning options, or different default behavior. When adding content to the user documentation that does not apply to all environments, call it out. For example:
**(Linux® only)**
If content is not marked it should apply to any platform.
See Trademarks for information about marking trade names appropriately.
The user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in various versions of the OpenJDK runtime. However, due to differences between the Java™ SE class libraries, specific options might apply only to one environment. The following icons are available to indicate where differences apply:
- For content that applies only to an OpenJDK version 8.
- For content that applies to an OpenJDK version 8 or later version.
- For content that applies only to an OpenJDK version 11.
- For content that applies to an OpenJDK version 11 or later version.
- For content that applies only to an OpenJDK version 15.
- For content that applies to an OpenJDK version 15 or later version.
- For content that applies only to an OpenJDK version 16.
- For content that applies to an OpenJDK version 16 or later version.
- For content that applies only to an OpenJDK version 17.
- For content that applies to an OpenJDK version 17 or later version.
- For content that applies only to an OpenJDK version 18.
- For content that applies to an OpenJDK version 18 or later version.
Different colors are used for the icons to differentiate long term service (LTS) releases from feature releases. For accessibility reasons it is important to use alternative text with these icons that differentiates an LTS release.
Follow these guidelines:
- If a topic is exclusive to a particular version, use the icon near the top of the topic.
- If the content applies to a cell or row in a table, use the icon within the table.
- If the content applies to a sentence within a topic, encapsulate the content by using an end tag
for LTS releases or 
for feature releases.
Here are some examples:
 This sentence applies only to Java 8 runtime environments that include the OpenJ9 VM. 
 This sentence applies only to Java 16 or later runtime environments that include the OpenJ9 VM. 
In each topic, the first occurence only of trademarked terms should be marked appropriately. Avoid including trademark symbols in titles, headings, etc., unless the term appears nowhere else in the topic.
Here are some examples that you might come across:
AIX®, IBM®, IBM z15®, Java™, Linux®, Linux on IBM Z®, Linux on Power Systems™, macOS®, MVS™, OpenJ9 VM Language Environment®, Oracle®, Windows™, z/OS®.
Mark trademarks™ with ™ (as in Java™) and registered trademarks® with ® (as in Linux®).
If you believe that a diagram can be used to enhance the content, add the .gif or .png file to the docs/cr folder and reference it in the markdown file using the following syntax:
Font-awesome icons can also be used to highlight user "notes" and "restrictions". The following examples show how to embed these icons:
:fontawesome-solid-pencil-alt:{: .note aria-hidden="true"} **Note:** Here is something you should be aware of...
:fontawesome-solid-exclamation-triangle:{: .warn aria-hidden="true"} **Restrictions:** Here is some limitations...
Font-awesome icons are also used in option tables to indicate defaults. The following examples show how to embed these "ticks" and "crosses".
:fontawesome-solid-check:{: .yes aria-hidden="true"}<span class="sr-only">yes</span>
:fontawesome-solid-times:{: .no aria-hidden="true"}<span class="sr-only">no</span>
Note that these require an extra <span>, which is used by screen readers.
For examples that embed Java version icons such as 
and 
, see Which OpenJDK version?.
The user documentation pulls in API documentation, which is pre-built as HTML files. These files have to be referenced in a specific way for the build process. The documentation has two builds, one for use in the web site and a special build for offline use. The offline build uses the Mkdocs use_directory_urls: false configuration setting, which alters the layout of the site and automatically adjusts relative urls between Markdown files. However, relative urls to non-Markdown pages, which are copied as-is into the /site directory, are not adjusted.
If you need to reference a specific API page from a Markdown file use the variable config.use_directory_urls provided by mkdocs-macros plugin. For example in the OpenJ9 JDK 11 API documentation, the iframe element uses this technique in the src attribute:
{% if config.use_directory_urls %}../{% endif %}api/jdk11/index.html?view=embed
To ensure that the contribution process is as simple as possible, the mkdocs-macros plugin should not be used for any other purpose than referencing pre-built API documentation.
The accessibility of the documentation to users with disabilities is important to this project. Here are some things to consider:
- Don't use terms that convey "position". For example, do not write "the example below", "the above table", "the right-hand column" and so on.
- Don't use color on its own to differentiate text. For example, "the string shown in green" or "the code element in blue".
- If you embed a diagram, use alternative text (ALT-TEXT) to describe the image for screen readers. See Using images.
- If you use icons to indicate content for a specific OpenJDK version, or for "notes" and "restrictions", add the correct attributes for screen readers. See Using images.
When you've made the changes that you want to contribute, build and preview the website. If you have set up an MkDocs environment locally, follow these steps:
- Run
mkdocs serve. - Open a browser and view the following URL: http://127.0.0.1:8008 (specifically, the URL set in the
dev_addr:section of themkdocs.ymlfile.
When you are happy with your changes, create a pull request, following the guidelines for submitting a contribution to OpenJ9 here.
In particular, if your changes address an issue, quote the issue number in the commit message.
If work is ongoing, or if there is further work to be done after you create your pull request, (either in the docs or in the code) add a "WIP" (Work In Progress) prefix to the title.
Pull requests must be previewed before merging. Stage your pull request (i.e. create a temporary draft of your changes) by triggering a Jenkins-ci job. To run the job, add the following trigger comment into a pull request:
Jenkins doc stage
Pull request builds are staged at the gh-pages branch of the https://github.com/eclipse-openj9/openj9-docs-staging repository. To view the staged draft of your documentation, visit the following URL, substituting <PR> with the number of your pull request:
https://eclipse-openj9.github.io/openj9-docs-staging/<PR>
(approved users only)
Project committers are responsible for checking pull requests and merging changes.
Documentation pull requests must not be merged before code pull requests are merged in case subsequent code changes alter the documented behavior.
Before merging, check with the developers involved and make sure that there is not work still to be done. This is usually indicated by a "WIP" prefix on the pull request title.
When pull requests are merged, the documentation is published to the gh-pages branch of the https://github.com/eclipse-openj9/openj9-docs repository as part of the "current working draft" at the following URL:
https://eclipse-openj9.github.io/openj9-docs
When released, the latest version of Eclipse OpenJ9 is published at:
https://www.eclipse.org/openj9/docs
For more information about the documentation release process, build process, and publication process, see the wiki section of this repository.