Skip to content

Latest commit

 

History

History
132 lines (88 loc) · 4.27 KB

STYLE_GUIDE.adoc

File metadata and controls

132 lines (88 loc) · 4.27 KB

Jakarta EE Tutorial Style Guide

This document describes the requirements for new writing contributions to the Jakarta EE Tutorial; it includes a mixture of writing and Asciidoc / Antora guidelines.

Eclipse Writing Style Guide

New contributions must follow the Eclipse Writing Style Guide in addition to the guidelines mentioned herein. If there is a conflict, the guidelines in this document take precedence.

Tone and Voice

Use a first-person voice but a professional tone and avoid slang. New tutorial material should be easy to read and approachable.

For more guidelines, see Tone and Voice.

Common Words, Names, and Abbreviations

When using the following words, names, and abbreviations, consistently use the spelling and capitalization below:

  • "Basic authentication"

  • "Form authentication"

  • WAR

  • JAR

  • HTML

  • Profile names should be capitalized (Core Profile, Web Profile, etc.)

Using Hyphens

Be aware of when to use a hyphen, especially for multiple-word adjectives before or after a noun. For example, "water-based paint" and "paint that is water based". See this article and Compound Words and Hyphenation for details.

Lists

For lists, use:

  • A colon before the list

  • Auto-numbering Asciidoc syntax

  • Avoid repeating the same word at the beginning of each bullet point (for example, "Use" or "Execute")

  • Use a period at the end of complete sentences, but don’t use a period otherwise.

For example:

You'll learn how to:

. Define security constraints
. Provided authentication mechanisms
. How to set a provided identity store that uses a database

See Lists for more details.

Internal Links

You can easily link to other headings in the current document. For example, given the following heading:

== This is My Header

You can link to it like so:

Ths is a link to my header: <<_this_is_my_header>>

Links to Other Pages

Links to other pages in the tutorial should be in the following format:

* xref:module-name/file-nameo.adoc#_anchor_name[Link Text]

For example:

* xref:security-intro/security-intro.adoc#_introduction_to_security_in_the_jakarta_ee_platform[Introduction to Security in the Jakarta EE Platform]

See the Antora xref docs for more information.

Tip
 If you want to give a heading a permanent identifier, you can add an anchor to the section and use that instead.

Titles for Images and Tables

Images and tables should be given a title using the asciidoc title syntax starting with a dot. This can be preceded with an anchor using underscores. For example:

[[_anchor_name]]
.Image Title
image::image-path.svg["Image Alt Text"]

Links to the image or table can be created using the anchor name and either the internal or external link instructions as given for headers above. For example:

 <<_anchor_name>>

Note the labels for table captions can be turned on and off using the table-caption document attribute in antora.yml

Definitions

Use bold for a word when defining it. For example, "Java is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible." (Wikipedia)

Line Breaks

Use a line break after a substantial unit of thought, such as a sentence or after an important comma. For details, see Semantic Line Breaks.

Use of etc., e.g. and i.e.

In short, don’t use them etc., e.g., and i.e. See Latinisms.

Conventions