Contributing to the documentation
The user documentation is authored in markdown and built into HTML using Mkdocs, with a mkdocs-material theme. If you want to contribute to the documentation, we recommend that you install a local test environment for editing and previewing your changes. If you don't want to contribute to the documentation 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:
- General documentation enhancements / ideas for improvements
- Documentation errors or inaccuracies
- New content as a result of code changes at the Eclipse OpenJ9 repo
Table of contents:
- Setting up a local MkDocs environment
- Editing the documentation
- - Documentation structure
- - Style guidelines
- - Writing tips
- - Which platform?
- - Which OpenJDK version?
- - Using images
- - Accessibility
- Testing your changes locally
- Submitting a contribution
- Accepting contributions
Setting up a local MkDocs environment
- Python 3
- Pip 9.0.1
- a markdown editor E.g. Atom
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
- Fork the repository: https://github.ibm.com/runtimes/openj9-docs
- Clone the repository:
git clone email@example.com:<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
Editing the documentation
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: setting
Under pages:, 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.
Documentation content is contained in the following directories:
- All markdown files are in the
- All diagrams used in content are in the
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. Join the channel here.
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: if in doubt, avoid.
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:
If content is not marked it should apply to any platform.
Which OpenJDK version?
The user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in an OpenJDK version 8 or OpenJDK version 9 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 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 12.
- - For content that applies to an OpenJDK version 12 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 end tag for feature releases.
Here are some examples:
![Start of content that applies only to Java 8 (LTS)](cr/java8.png) This sentence applies only to Java 8 runtime environments that include the OpenJ9 VM. ![End of content that applies only to Java 8 (LTS)](cr/java_close_lts.png)
![Start of content that applies only to Java 10 and later](cr/java10plus.png) This sentence applies only to Java 9 or later runtime environments that include the OpenJ9 VM. ![End of content that applies only to Java 10 and later](cr/java_close.png)
If you believe that a diagram can be used to enhance the content, add the .gif or .png file to the
docs/images folder and reference it in the markdown file using the following syntax:
![Add alternative text here to describe the image for users who are using a screen reader](images/my_image.png)
Font-awesome icons can also be used to highlight user "notes" (
<i class="fa fa-pencil-square-o" aria-hidden="true"></i> **Note:** Here is something you should be aware of.
<i class="fa fa-exclamation-triangle" aria-hidden="true"></i> **Restrictions:** Here is something you should be aware of.
Font-awesome icons are also used in option tables to indicate defaults. The following examples show how to embed these "ticks" (
<i class="fa fa-check" aria-hidden="true"></i><span class="sr-only">yes</span>
<i class="fa fa-times" aria-hidden="true"></i><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 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.
Testing your changes locally
When you've made the changes that you want to contribute, build and preview the website. If you set up an MkDocs environment locally, follow these steps:
- Open a browser and view the following URL: http://127.0.0.1:8000
/site folder, which contains the HTML for the website.
Submitting a contribution to OpenJ9 documentation
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.
Project committers are responsible for checking pull requests and merging changes.
Previewing pull requests (whitelisted users only)
Pull requests must be previewed before merging 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-docs-staging repository. To view a draft of the documentation, visit the following URL, substituting <PR> with the Pull request number:
When PR requests are merged, the documentation is published to the gh-pages branch of the https://github.com/eclipse/openj9-docs repository at the following URL:
The latest release of Eclipse OpenJ9 is published to https://www.eclipse.org/openj9/docs.