Writing Documentation

Another great way to contribute to Jetty is to help us write and maintain our documentation.

Documentation guides

Jetty’s documentation is grouped into three guides, each written for a different target audience.

Operations Guide

Targets sysops, devops, and developers who want to run Jetty as a standalone web server.

Programming Guide

Targets developers who want to use the Jetty libraries in their applications.

Contribution Guide

Targets developers and writers who want to make contributions to the Jetty project.

The documentation toolchain

Jetty follows a "docs as code" philosophy, meaning we use the same tools to write and build our code and docs. As such, the docs are maintained directly within the Jetty codebase at documentation/jetty-documentation/src/main/asciidoc/.

AsciiDoc

Our docs are written in AsciiDoc, a markup language for writing technical content. AsciiDoc supports many advanced features, such as robust linking across different documentation sets, while remaining human-readable.

Although Jetty takes advantage of many of these features, you don’t need to be an AsciiDoc expert to contribute to our documentation. If you are interested in learning the ins and outs of AsciiDoc, the official language documentation is a good place to start.

Maven and Asciidoctor

TODO UPDATE FOR ANTORA

In addition to using Maven to build the Jetty codebase, we use it to build our docs. During a build, Maven converts AsciiDoc-formatted docs into the HTML pages that you are reading right now.

Asciidoctor is the tool that actually performs this compilation step. Maven integrates with Asciidoctor via the asciidoctor-maven-plugin.

Building the docs

TODO UPDATE FOR ANTORA

Since Jetty’s docs are maintained in git alongside the rest of the Jetty codebase, you’ll need to check out a local copy of the code to contribute to the docs.

The docs are maintained as a separate module within Jetty, which means you can build the docs separately from the rest of the project. To do so, run mvn clean install from the documentation/jetty-documentation subdirectory.

$ cd jetty.project/documentation
$ mvn install
<...snip...>
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.272 s
[INFO] Finished at: 2018-04-09T13:06:10-05:00
[INFO] Final Memory: 74M/247M
[INFO] ------------------------------------------------------------------------
== You’ll see a lot of files getting downloaded during the build process. This is Maven setting up the execution environment, which it uses to generate the docs. ==

When the build completes, you can view the generated docs in your preferred web browser by opening file:///path/to/jetty.project/documentation/jetty-documentation/target/html/index.html on your local filesystem.

Documentation project structure

TODO UPDATE FOR ANTORA

The documentation root is documentation/jetty-documentation/. Within this root directory are some files and subdirectories of note:

src/main/asciidoc

The primary root for all documentation content.

src/main/asciidoc/config.adoc

This file contains metadata and global variables shared across all the documentation guides. This configuration is used by Asciidoctor to correctly render the final docs.

src/main/asciidoc/*-guide

Secondary root directories for each individual documentation guide.

src/main/asciidoc/*-guide/index.adoc

Asciidoctor’s "point of entry" for each guide. Content is pulled into the guide via the include:: directives in these index files. Also, guide-specific metadata and variables that wouldn’t belong in the root config.adoc can also be defined here.

target/<format>

The final build destination for any docs generated by Maven. By default, docs are generated into target/html, but other formats (e.g., pdf and epub) are available. This directory is not checked into git.

Style guide

The following conventions are not set in stone, but you are encouraged to follow them where possible. Stylistically consistency helps keep the docs easy to both understand and maintain.

Ventilated prose

In markup, each sentence should be on its own line with a hard return at the end of the line. This practice is known variously as ventilated prose or semantic linefeeds.

This practice makes for more readable file diffs, and also makes it easier to comment out individual lines or to move sentences around.

== AsciiDoc treats a single line breaks just like a space, so it will render ventilated prose naturally. ==

Documenting versions

Documenting multiple versions at once

TODO UPDATE FOR ANTORA AND FORTHCOMING EE11

Jetty 12 features many parallel modules with similar names and functionality, but which target different versions of Jakarta EE. For instance, the ee8-deploy, ee9-deploy, and ee10-deploy modules all behave similarly, except they target Jakarta EE8, EE9, and EE10, respectively.

Whenever possible, try to consolidate these types of parallel references. For instance, you can quickly refer to all three of the aforementioned modules as a group by writing ee{8,9,10}-deploy or eeN-deploy.

Another approach is to write your docs targeting one specific module, and tell the reader what substitution(s) they would need to make to target a different module.

== When targeting a specific version in your docs for demonstration purposes, you should prefer to use the most recent version number. For the example above, this would mean targeting ee12-deploy. ==

Consolidating parallel references saves readers from having to sift through repetitive material, and helps us avoid maintaining multiple versions of nearly identical docs.

Dealing with multiple versions in code examples

Instead of referencing multiple versions in your code and command-line examples, it’s generally better to target one specific version, typically the latest (currently ee12):

$ java -jar $JETTY_HOME/start.jar --add-modules=ee12-deploy

This will work when copy-pasted into the command line.

== You may want to remind the reader to change the 10 in the command to their preferred target version — although doing so isn’t strictly necessary for a simple example like above. ==

License blocks

Each .adoc file should contain the license block that exists in the index.adoc file. For reference, here is a standard license header:

//
// ====================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ====================================
//

AsciiDoc conventions

TODO UPDATE FOR ANTORA

Custom IDs

We rely heavily on custom IDs for generating stable documentation URLs and linking within docs.

At minimum, every chapter and top-level section should have its own custom ID; however, best practice is to give each subsection its own custom ID, too.

== Custom IDs share a single global namespace, which means they must be unique across all documentation guides. To help deal with this constraint, we used different ID prefixes in each guide:

  • Operations Guide: og-

  • Programming Guide: pg-

  • Contribution Guide: cg- ==

Images

Images should live in the images/ directory of the guide they appear in. Use the image:: directive to include an image, like so:

image::small_powered_by.gif[image,width=145]
image

Admonitions

Admonitions (or "callout blocks") are useful for flagging information that doesn’t belong in the natural flow of text. Asciidoc supports five levels of admonition:

  • [NOTE]

  • [IMPORTANT]

  • [TIP]

  • [CAUTION]

  • [WARNING]

Each admonition’s visual appearance and typical usage situation are as follows:

== A note about the previous case to be aware of. ==
== Important notes are marked with an icon. ==
== Tips that make your life easier. ==
== Places where you have to be careful what you are doing. ==
== Where extreme care has to be taken. Data corruption or other nasty things may occur if these warnings are ignored. ==