Skip to content

Latest commit

 

History

History
332 lines (218 loc) · 14.5 KB

CONTRIBUTING.adoc

File metadata and controls

332 lines (218 loc) · 14.5 KB
Raw

Contribute to the Bonita documentation content

Table of Contents

We are pleased to receive any kind of contribution (issues, pull requests, suggestions …​).

Theme online example

A website is available to show you what is possible with our Bonita theme.

Contribution check

Before opening a pull request, please check our few recommendations:

Verify that each updated adoc file starts with:

= A short title
:description: Put just after title (without whitespace) a short description to explain what we can retrieve in this page.

You can put you content after metadata block
ℹ️
 This metadata information is useful to improve our visibility for search engine (SEO)

Short presentation of the documentation environment

AsciiDoc is the markup language chosen to write our documentation content. You can check the official documentation site to learn more on AsciiDoc syntax.

If you know the Markdown syntax, please check the AsciiDoc vs Markdown documentation comparison to speedup the learning.

We are using Antora to generate the Bonita documentation.

For more details about how the generation works, see the Architecture documentation and the development documentation.

Tips for writing the documentation content

Media

Prefer source code documentation to code screenshot images

Please don’t add screenshot of source code, configuration file. This has the following issues

  • maintenance: typo fixes, updates, …​ can not be managed easily. Differences between documentation are harder to manage (binary merge issues)

  • the source cannot copy/paste for reuse

  • image content is larger than text, so this slow down the site display (especially on mobile if the image is too large) and increase the bandwith consumption in the infrastructure (increase bill)

  • the AsciiDoc code support is very easy to set up and powerful. See Source Code documentation

  • for an example of image to source example replacement, check Bonita 2021.1 product-versioning replacement

Variables and attributes

You can define AsciiDoc attributes in the antora.yml file at repository root and reference it in content page. For a detailed documentation about attributes, see the AsciiDoc attribute documentation.

asciidoc:
  attributes:
    bonitaVersion: 2021.1
Use {bonitaVersion} syntax to reference this attribute in content. It will be replaced by 2021.1 for each occurrence.

Disabling attribute substitution

Any elements around braces are interpreted as attribute and so, they will be substituted in the generated output. If the value around braces is not related to a declared attributes, warnings are emitted when generating the html files.
For instance, in ${CATALINA_HOME}/conf/jaas.cfg, CATALINA_HOME is substituted by default which is not something we want as we want to document an example with bash substitution.

To disable attribute substitution in inline text, use one of the following:

  • add a ` character around an inline code extract like `+${CATALINA_HOME}/conf/jaas.cfg++

  • add a \ character before the first brace: $\{CATALINA_HOME}/conf/jaas.cfg. This is the sole way to do it in a block where the subs="attributes" macro is enabled. See Blocks and Substitutions in Blocks

Attributes substitution in blocks

Notice that by default there is no attribute substitution in blocks, so extra configuration is needed in that case. More details are available in https://docs.asciidoctor.org/asciidoc/latest/subs/apply-subs-to-blocks/

We recommend to use explicit macro on part of the block that requires substitution. This allows to mix the {..} for elements that should not been substituted (for instance, maven properties or bash variables).

In the block, enable the macros by adding the subs configuration like [source,xml,subs="+macros"] and in the block content, set {...} around the attribute you want to substitute. For instance, <bonita.version>{bonitaVersion}.0</bonita.version>.
This configuration then let parts like <version>${bonita.version}</version> not substituted.

It is also possible to configure substitution globally for the block (see the documentation).

Bonita editions admonitions

When Bonita editions are referenced, to avoid different wording, the following rules should apply:

Before 2023.2 Since 2023.2

For Enterprise, Performance and Efficiency editions only.

For Subscription editions only

For Efficiency, Performance, and Enterprise editions only

For Subscription editions only

For Performance and Enterprise editions only

For Subscription editions only

For Enterprise edition only

For Subscription editions only
⚠️

Since 2023.2 version, use Subscription editions instead of Enterprise, Performance, and Efficiency editions in the documentation content too.

Tips about the files organization

File names

Always follow the kebab case convention. This is something we are going to progressively enforce in all repositories (see [#589](#589)), for consistency and to improve the SEO.

Do not prefix the file name with the name of the component (file are already stored in a dedicated component repository, the url already contains the component key) or a category (use Antora module instead to organize the content - see the next paragraph).

Do

  • my-super-page.adoc

  • explicit-architecture.png

  • nav-bonita-installation.adoc

Don’t

  • bc-app-declaration.adoc (component prefix and abbreviation): application-declaration.adoc

  • BC_archi_single.png (both component prefix and underscore): archi-single.png

  • livingapp_manage_configuration.adoc (module and underscore): manage-configuration.adoc in the living-app or living-application module (from the bcd component)

  • Service_Level_Agreement_Data_Management.adoc (module and underscore and uppercase): data-management.adoc in a service-level-agreement or sla module (from the cloud component)

ℹ️
 examples involving bc are taken from bonita-central-doc PR #9

Antora modules

You can use Antora modules to clarify content (for instance, getting-started guides, how-to articles).
See https://docs.antora.org/antora/3.1/module-directories/#module.

Modules allow to better separate content and resources (for instance specific images and attachments). For Bonita doc, this will avoid for instance to have all "getting started" pages at the same level as other pages (currently in the md folder): easier to identify what pages and images are related to "getting started", easier maintenance, …​.

Use alias to create redirects

IMPORTANT: not creating redirects impacts the SEO and the reader experience

You MUST create an alias when you do the following actions on a existing page

  • rename

  • move

  • delete

When doing such actions, the former url of the page is no more available, so its content is no more available for readers (HTTP error 404). The solution is to setup a redirect that will lead the reader to a new destination.

Antora provides the 'Alias' feature to deal with redirects

  • documentation writer knows where to redirect, so it create an alias in the target page that references the old page

  • the documentation build process creates a redirect for each alias

  • the reader is happy and always find the information in the documentation

Page aliases really were designed to address page renames/moves, particularly within a single component version. They aren’t a general-purpose URL router. They can be used for more than what I described, but then you really do have to think about what you are doing and use with care…​because it can quickly become confusing.

For more details about alias, see

Example 1: rename page

Assume that the be-happy.adoc is renamed into very-interesting.adoc.

After rename and alias setting, the content of the very-interesting.adoc should look like:

= Page title
:page-aliases: ROOT:be-happy.adoc

Example 2: move the page to another Antora module

Assume that the be-happy.adoc page was originally in the ROOT module and is moved to the version-update module.

After move and alias setting, the content of the be-happy.adoc in the version-update module should look like:

= Page title
:page-aliases: ROOT:be-happy.adoc

Testing the aliases

Changes in the documentation are done with Pull Requests and a live preview is available for each Pull Request to see the proposed changed.

So use the preview to test the alias configuration: <base_preview_url/bonita/2021.1/old-page-name should redirect to <base_preview_url/bonita/2021.1/new-page-name

Adding reference between pages of two components or between pages of 2 versions of the same component

⚠️
 DO NOT hard code urls with https://documentation.bonitasoft.com/xxxx or ../../my-page.adoc, use xref instead. An automatic check rejects your Pull Request if you hard code such links.

Rationale

  • https://opendevise.com/blog/referencing-pages/

  • such hard coded links only target the production environments, links won’t work in preview environments

  • not portable, such links cannot work if we want to generate the documentation in PDF format

The general form of a xref is xref:<version>@<component_name>:<module>:<page>#anchor and some elements are optional (version, module and anchor).

For more details about the xref syntax, see the Antora documentation to have a better understanding about version, component, module and anchor keyword:

Example:

  • abbreviated form: xref:bonita::about.adoc

  • a page in same component and same version: xref:ROOT:resource-management.adoc

  • a page of a given version in the ROOT module (explicit): xref:2022.2@bonita:ROOT:what-is-bonita.adoc

  • a page of a given version in the ROOT module (implicit): xref:2023.1@bonita::release-notes.adoc

  • a page of a given version in the version-update module targeting an anchor: xref:2023.1@bonita:version-update:update-tool-overview.adoc#prerequisites

For an example in the bonita documentation:

  • the BCD documentation contains links to various versions of the Bonita documentation (see PR #164).

  • the Bonita release-notes 7.9 contain a link to the latest BCD version (see PR #1494)

ℹ️

In the documentation content repository, when a PR is created, a preview site is generated and deployed to a preview environment. In the preview, the link may seem broken as that kind of preview may build a single component version so the targeted page are not available so not resolved. In any case, the xref is validated during the site preview build or by another build run that includes both the source and target component versions.

There is currently a work in progress to improve the xref validation and make the xref resolution also work in the PR preview. See issue #326.

Adding "Internal cross-references" i.e. reference to an anchor in the page

Define an explicit anchor. Do not use Automatic anchors that are generated from the text of heading and that are subject to change when the text changes (so, references would be broken when the text changes).

[#my-anchor]
== A paragraph
the content of the paragraph

Then, use the anchor as reference anywhere in the page

The content and the reference to <<my-anchor, My Anchor>>.

Resources

Make assets available as downloadable files

Examples

The examples directory can be used to store source code which can then easily be integrated in the documentation.
See https://docs.antora.org/antora/3.1/examples-directory/

This allows user to download the source as attachments by providing a link directly for the code (no duplication between the actual examples and the documentation)

Attachments

Attachments are also possible: https://docs.antora.org/antora/3.1/attachments-directory/ The syntax is described in https://docs.antora.org/antora/3.1/navigation/reference-resources/ (it uses the link macro)

💡

Antora 3 provides a new syntax for referencing attachments. See https://docs.antora.org/antora/3.1/navigation/reference-resources/
Please prefer this syntax when Antora 3 will be used to build the site: it allows detecting broken references because it uses the xref macro.