-
Notifications
You must be signed in to change notification settings - Fork 47
Stylistic guidelines
Copyright
Features
File names
Images
Links
"See also" links
Tables
Topic titles
Special characters
- Include copyright information as the first line of the file (commented out).
- Follow the
Copyright (c) 2019, 2020 IBM Corporation and others.format, where 2019 was the original year of publication, and 2020 was the year of the latest year the doc was updated.
- Write features in plain text (not monospaced).
- Avoid using specific feature versions whenever possible.
- Link to features the first time you mention them, except in the first paragraph.
- When linking to a generalized feature (no specific version), use the feature macro without the version number so that it defaults to the most recent version.
*The syntax for the feature macro is:feature:${code-name-of-feature-w/out-version#}[display=${text name of feature}]so for example, MicroProfile Health is:feature:mpHealth[display=MicroProfile Health]
- Write meaningful file names that give users an idea of what information is contained in the topic.
- Use all lowercase letters, and use hyphens (not underscores) to separate words.
- Don't use special characters or spaces.
- Only use gerunds if the topic is a task. For example,
configuring-spnego-authentication.adoc. - Open Liberty should be hyphenated in file names (
open-liberty).
In the Antora framework, images are stored within the modules where they appear. Images are stored in a special directory called images, within a parent directory called assets. For example, for docs in the ROOT module, images would be stored in ROOT/assets/images. With this directory structure, you don't need to specify a path to the image in the doc syntax, you can just specify the file name. For example, image::image-filename.png[]. For more information on images in Antora, see Image files
All images should include title and alt text. If possible, alt text should describe what the image shows in 50 characters or less. If a longer description is necessary you can incorporate it into the regular page content before or after the image. In AsciiDoc, the title is used to generate the caption if no caption is specified. Here is an example of the syntax to add alt text and a title for an image:
.A mountain sunrise
image::sunset.jpg[an image showing a sunset in the mountains]
In this example, the title (A mountain sunrise) is specified on the line before the image, after a period. The alt text is specified in square brackets after the image file.
See the full AsciiDoc image syntax in the quick reference guide.
- Include links in the OL docs when the information on the linked-to page provides beneficial and relevant information that is out of the scope of that particular topic. This might include:
- Background information
- Advanced information
- Reference information
- Empathize with the user when thinking about which links to include. Don't just dump a ton of links at the end of the topic.
- Before finalizing a new topic, search the OL docs and guides to ensure that you haven't overlooked any related topics that would be valuable to the user.
- Embed links rather than list them at the end of the topic whenever possible.
- Write link text to accurately reflect where the link will take the user.
- Don't include monospaced text in link text. For example, use "authFilter element" as link text, rather than "
authFilterelement". - When linking to a guide, let the user know that the link takes them to a guide. For example, "To learn how to provide system and application metrics from a microservice with MicroProfile Metrics, check out the Providing metrics from a microservice guide.").
- When linking to a feature, include "feature" in the link text. For example, use "the Request Timing feature" as the link text to the Request Timing feature.
- When linking to the feature's generated feature topic, use the macro (without the version number unless it's relevant only to particular versions). The following example shows the macro for the Application security feature:
feature:appSecurity[display=Application Security feature]Unversioned feature macros default to the latest version of the feature. To target an earlier version, include the version number:feature:featureName-x.x[display=Feature Name] - When linking to a feature configuration element, use the macro:
config:elementName[display=elementName] - When linking to other topics in the OL docs, use relative links, not absolute links. For example, For the MicroProfile Overview topic, use
xref:microprofile.adoc[MicroProfile Overview]. Note that the main Open Liberty topics and the Reference section topics are in separate Antora modules,ROOTandreference. If you need to link from a topic in one module to a topic in a different module, you must include the module name, as well as any subfolders other than/pages, in the relative link. The/pagessubfolder is part of the Antora framework and does not have to be included in the link. For example, to link to the Server Configuration Overview topic in the reference section from a topic in the ROOT module, usexref:reference:config/server-configuration-overview.adoc. To link from a topic in the reference section back to a topic in the ROOT module use the following syntaxxref:ROOT:filename.adoc[Name of topic].
You can add a See also section to the end of a topic to list helpful links. If possible, it's better to put links in the body of a topic, where you can also give context for why the user should care about the linked topic. Generally, the See also section should contain links that are relevant to the topic but not mentioned in the body of the topic. However, if in the body of your topic you link to a specific section of another topic, you can include a link to the entire topic in See also.
Put See also links in a bulleted list, unless there is only one item to list. Each bullet should contain only the title of the link destination. Do not include any other supporting or introductory text. If only a particular section of a topic is relevant, use an anchor to link directly to that section and include the section title in the link text.
For links to Open Liberty guides, preface the title with the word Guide:, for example:
Guide: Testing a MicroProfile or Jakarta EE application
For links to Open Liberty blogs, preface the title with the word Blog:, for example:
Blog: How to analyze Open Liberty Logs with Splunk
If you are linking to a section of a release blog post, use the section title as the link text, for example:
Blog: HTTP access log fields in JSON logs
If you need to link to an external site for more information on a product, specification, protocol, etc., whenever possible link directly to the original source of information rather than a third party source. For information about a product or technology, link directly to the vendor or open source project.
All tables should include a title, caption, and header row. In AsciiDoc, the title is used to generate the caption if no caption is specified. Also, make sure to include a text introduction to the table. Here is an example of a simple table with text introduction, title/caption, and header:
The following table shows the syntax for a two-column table:
.A proper table
[%header]
|===
|Name of Column 1 |Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
The [%header] annotation specifies the first table row as the header. The title, specified after the period, is used to build the HTML caption. For AsciiDoc table syntax, see:
- Only use gerunds if the topic is a task, for example, "Configuring SPNEGO authentication".
- Use a title alias in the navigation if the title is long and can be effectively shortened.
Some special characters might be affected by our build processing. In these cases, you must determine the proper escape character to allow the special character to appear in the docs output. As we find them, we document these characters in this section.
| character | Escape syntax |
|---|---|
| + | pass:[+] |
| | | \| |
Additional resources: