Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
235 lines (161 sloc) 12 KB

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:

Table of contents:

Setting up a local MkDocs environment

Basic pre-requisites:

  • Git
  • 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

Next:

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

Documentation structure

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 /docs folder.
  • All diagrams used in content are in the /docs/images folder.

Style guidelines

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.

Writing tips

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.

Which platform?

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.

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:

  • Java 8 icon - For content that applies only to an OpenJDK version 8.
  • Java 11 icon - For content that applies only to an OpenJDK version 11.
  • Java 11 and later icon - For content that applies to an OpenJDK version 11 or later version.
  • Java 12 icon - For content that applies only to an OpenJDK version 12.
  • Java 12 and later icon - 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 end tag for LTS releases for LTS releases or end tag end tag for feature releases 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)

Using images

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" (📝) and "restrictions" (⚠️). The following examples show how to embed these icons, which include some important attributes for accessibility:

<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" (✔️) and "crosses" (✖️).

<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 Java 8 icon and Java 12 and later icon, see Which OpenJDK version?.

Accessibility

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:

📝 MkDocs creates a /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.

Accepting contributions

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:

https://eclipse.github.io/openj9-docs-staging/&lt;PR>

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:

https://eclipse.github.io/openj9-docs

The latest release of Eclipse OpenJ9 is published to https://www.eclipse.org/openj9/docs.

You can’t perform that action at this time.