Unverified Commit a080cea1 authored by Benjamin Parisel's avatar Benjamin Parisel Committed by GitHub
Browse files

doc: initiate the documentation for Technical Writer (#142)


Co-authored-by: default avatarThomas Bouffard <27200110+tbouffard@users.noreply.github.com>
Co-authored-by: default avatarAdrien <adrien.lachambre@bonitasoft.com>
Co-authored-by: default avatarhugues.bretin <hugues.bretin@bonitasoft.com>
parent 24116284
......@@ -4,21 +4,21 @@ We are pleased to receive any kind of contribution (issues, pull requests, sugge
== Commit message format
Here is the expected commit format, please follow https://www.conventionalcommits.org/en/v1.0.0/[conventional commits rules]. We give you a little summary about basic commit templating message.
Here is the expected commit format, please follow https://www.conventionalcommits.org/en/v1.0.0/[conventionnal commits rules]. We give you a little summary about basic commit templating message.
```
[source]
----
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
----
== Pull request
Each improvment, fix must be submit with a pull request. When a pull request is submit, a action is running to check if your pull request follow commit message format.
For each improvement, the fix must be submitted with a pull request. When a pull request is submitted, an action is run to check if the pull request follows the commit message format.
== Intregration policy
== Integration policy
By default, all pull requests is squash when Maintainer has validated your contribution. If you don't want squash your commit, please tell us by a comment in your pull request.
= Developers documentation
= How-to documentation
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
== For Documentation Content Writers
* xref:content/CONTRIBUTING.adoc[Guidelines for contributing to documentation content]
== Developers documentation
* xref:documentation-components-and-versions.adoc[Documentation Content: Component and Versions management]
* xref:architecture.adoc[Architecture Overview]
* Tips for Documentation Content Writers
** xref:documentation-versions.adoc[Documentation Content Versions]
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
* migration from the old documentation site (archives)
** xref:./migrate-from-old-documentation-site/doc-content-conversion-from-md-to-adoc.adoc[Convert markdown content to asciidoctor]
** xref:./migrate-from-old-documentation-site/migration-steps-put-the-site-live.adoc[Migration to put the site live]
......@@ -2,6 +2,8 @@
This document provides details on the architecture of the documentation site, in order to ease future developments.
image::images/DocToCloud-Architecture-BigPicture.png[]
== Chore solution: https://antora.org/[Antora]
Antora is a multi-repository documentation site generator.
......
= Contribute to the Bonita documentation content
:icons: font
:toc:
:toclevels: 4
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
We are pleased to receive any kind of contribution (issues, pull requests, suggestions ...).
== Contribution check
Before opening a pull request, please check our few recommendations:
Verify that each updated `adoc` file starts with:
[source,adoc]
----
= 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
----
NOTE: This metadata information is useful to improve our visibility for search engine (SEO)
== Short presentation of the documentation environment
https://docs.asciidoctor.org/asciidoc/latest/[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 https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown[Asciidoc vs Markdown]
documentation comparison to speedup the learning.
We are using https://docs.antora.org/[Antora] to generate the Bonita documentation.
For more details about how the generation works, see the xref:../architecture.adoc[Architecture documentation] and the
xref:../README.adoc[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
* for an example of image to source example replacement, check https://github.com/bonitasoft/bonita-doc/pull/1492[Bonita 2021.1 product-versioning replacement]
==== Embed videos
It is possible to embed videos as it is done in Bonita 2021.1 index page: https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/
* A default/max size is set for the mobile view
* there is no default for the desktop view at the moment, so you should set the dimensions when declaring the `video` macro
as in the following example
[example]
+video::038g85tvzo4[youtube, width=640,height=380]+
==== Asciinema
https://asciinema.org/[Asciinema] provides a great way for sharing shell sessions recording, making documentation more lively !
Once you have created a `.cast` file, you can add it to your document with the following markup
.sample asciinema adoc.
[source, asciidoc]
----
== Asciinema embedded
Example of embedded asciinema recording:
++++
<asciinema-player src="_images/images/<path_to_your_cast_file>.cast" speed="2" theme="monokai" title="Example of embedded asciinema recording" cols="240" rows="32"></asciinema-player>
++++
----
The generated asciidoctor (before transformation by Antora) document should render like something like this:
[.thumb]
image::images/asciinema_sample_rendering.png[]
=== Cards
You can use card style in your page. Please don't abuse it, and try to only use it on index pages.
.Card display in after HTML generation
You can update *link*, *title* and description for each card.
To do it, you need to use this following syntax:
[source,adoc]
----
[.card-section]
== Highlight
[.card.card-index]
--
yourInternalOrExternalLink[[.card-title]#Card Title# [.card-body.card-content-overflow]#pass:q[You can write a short description here to display it in the card body.]#]
--
----
You can use many cards in same card section. +
Please keep this technical syntax to avoid error.
NOTE: If you want to see a real example, please consult the index.adoc file in https://github.com/bonitasoft/bonita-doc/blob/7.12/md/index.md[bonita documentation GitHub repository].
WARNING: If description in card body is too long (more than 3 lines), we will hide the excess.
=== 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 https://docs.asciidoctor.org/asciidoc/latest/attributes/attribute-entry-substitutions/[asciidoc attribute documentation].
[source,yml]
----
asciidoc:
attributes:
bonitaVersion: 2021.1
----
[example]
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, Asciidoctor tries to substitute them. 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+`, Asciidoctor tries by default to substitute `CATALINA_HOME` which is not something we want
as we want to document an example with bash substitution.
To disable attribute substitution in inline text, add a `+` character around the text that contains the braces
* globally around an inline code extract like `\+${CATALINA_HOME}/conf/jaas.cfg+`
* just around the braces: `$+{CATALINA_HOME}+/conf/jaas.cfg`
See https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/#inline-passthrough-macros for more details.
==== 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 `pass:a[{...}]` around
the attribute you want to substitute. For instance, `<bonita.version>pass:a[{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).
=== Admonitions
What are Admonitions: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions
==== GitHub may not render admonitions
See this https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/#using-emoji-for-admonition-icons[asciidoc documentation] for more details.
==== Custom admonition for Cloud
see https://github.com/bonitasoft/bonita-documentation-theme/pull/53
=== Antora modules
You can use Antora modules to clarify content (for instance, getting-started guides, how-to articles). +
See https://docs.antora.org/antora/2.3/module-directories/#module.
[quote]
____
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, ....
____
=== Alias when renaming pages
IMPORTANT: Impact on SEO
See https://docs.antora.org/antora/2.3/page/page-aliases. +
Successfully experimented in https://github.com/bonitasoft/bonita-ici-doc#123
=== Adding link between two components or between versions of the same component
For instance
* the BCD documentation contains links to various versions of the Bonita documentation (see https://github.com/bonitasoft/bonita-continuous-delivery-doc/pull/164[PR #164]).
* the Bonita release-notes 7.9 contain a link to the latest BCD version (see https://github.com/bonitasoft/bonita-doc/pull/1494[PR #1494])
To avoid introducing hard coded url, follow the Antora documentation (see https://opendevise.com/blog/referencing-pages/ for rationale)
* https://docs.antora.org/antora/2.3/page/page-id/
* https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/
[WARNING]
====
The generated site available in PR preview in the document content repository is not able to resolve such references, as
that kind of preview only build a single component version.
To be able to see them during documentation content writing, you need to build the documentation with both the source and
target component versions. See https://github.com/bonitasoft/bonita-documentation-site/pull/222[PR #222] for more details.
====
=== Make assets available as downloadable file
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/2.3/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 are also possible: https://docs.antora.org/antora/2.3/attachments-directory/
= Documentation Versions
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
CAUTION: this is a work in progress
NOTE: the following mainly applies to the Bonita Platform documentation part
== Bonita versions that are documented
For Bonita, the rule is the following one: +
We document the 4 currently supported Bonita versions, and **the 4 versions before**. +
=== Impact on Algolia DocSearch
Each time a new version of a documented Bonitasoft project is released, this DocSearch configuration file has to be updated:
- The latest version has to be added to the projects to index
- The oldest version should be removed from the projects to index
-> It means that the DocSearch conf file should reflect this behavior.
== Versions lifecycle
NOTE: *this is a work in progress*. TODO link lifecycle actions to the how-to later described in this page
NOTE: this mainly applies to Bonita Platform but all components with multi-supported versions should follow the same rules
GA release (actions to be performed detailed later in this document):
* remove the prerelease configuration (see below)
* update the redirect to make the latest token url go to the new GA version
* archive the oldest version
* mark the 5th version as out of support: On new Bonita Platform GA release, an old version is considered as out of support.
== DocSearch and component versions
=== Don't use Antora component without version
No version Antora component: https://docs.antora.org/antora/2.3/component-with-no-version/
The documentation site search crawling and widget we have setup, require a component and a version. In case of version less
components, there is no version token in the url, so this defeats the mechanism in place.
See https://github.com/bonitasoft/bonita-ici-doc/pull/127#discussion_r585309113 for extra information.
=== DocSearch configuration
The DocSearch configuration is public and can be updated by submitting Pull Request: https://github.com/algolia/docsearch-configs/blob/master/configs/bonitasoft.json
See https://github.com/algolia/docsearch-configs/pulls?q=is%3Apr+sort%3Aupdated-desc+bonitasoft[past Pull Requests] for inspiration.
== General how-to for components and versions management
=== How to integrate a new component
Add a new source in the Antora playbook and reference a new branch. In this branch, put a `antora.yml` file at root which contains:
To add a new component, you first need to create a GitHub repository which will contain the asciidoc sources of this component
(i.e. the documentation content). This repository must be organized according to the https://docs.antora.org/antora/2.3/organize-content-files/[Antora recommendations].
You can check existing repositories for working examples.
At minimum, it will contain an `antora.yml` file at its root
[source,yml]
----
name: componentName
title: yourTitle
version: yourVersion
asciidoc:
attributes:
# define here attributes you need to templatize the documentation content or the html generation
nav:
- modules/ROOT/taxonomy.adoc
----
Then, you need to add a new source in the https://github.com/bonitasoft/bonitasoft.github.io/blob/master/antora-playbook.yml[Antora playbook].
A source references the URL of the repository and all the branches to retrieve.
Finally, you have to update the https://github.com/algolia/docsearch-configs/blob/master/configs/bonitasoft.json[search configuration]
to make this component searchable.
=== How to integrate a new version of an existing component
When we need to add a new version of one component, we need to:
. Create a new branch (in the repository related to the component)
. To add a new component, you first need to create a GitHub repository which will contain the asciidoc sources of this component (i.e. the documentation content).
This repository must be organized according to the https://docs.antora.org/antora/2.3/organize-content-files/[Antora recommendations].
You can check existing repositories for working examples.
. Then, you need to add a new source in the https://github.com/bonitasoft/bonitasoft.github.io/blob/master/antora-playbook.yml[Antora playbook].
A source references the URL of the repository and all the branches to retrieve.
. Finally, you have to update the https://github.com/algolia/docsearch-configs/blob/master/configs/bonitasoft.json[search configuration]
to make this component searchable.
=== How to remove a component version and make an archive available
On new Bonita Platform GA release, an old version must be archived.
. Take the oldest one
. Run the archive GitHub Actions: this creates a new tag on the related component version
. Create a PR targeting the bonita-doc archives branch and add the new archive version to the list
. Remove the version from the Antora Playbook
. Remove the version from the Algolia DocSearch configuration
. Add a redirect to manage urls of the old version. See https://github.com/bonitasoft/bonita-documentation-site/pull/182[PR #182],
https://github.com/bonitasoft/bonita-documentation-site/pull/195[PR #195] or https://github.com/bonitasoft/bonita-documentation-site/pull/201[PR #201]
. in the documentation content repository, remove the GH workflow that triggers the push to production
. .... *TODO* more info here, and link with lifecycle
=== Mark version as 'Out of Support'
Edit the related antora.yml file of the component version, and make the pages non-editable
[source,yml]
----
name: componentName
....
asciidoc:
attributes:
# remove the 'Edit this Page' link in all pages
page-editable: false
# display a dedicated banner to warn the reader about the out-of-support state
page-out-of-support: true
----
=== Pre-release versions
apply to beta and RC versions
See https://docs.antora.org/antora/2.3/component-prerelease/ to know how to
* mark a prerelease version
* display beta/rc additionnal information in the version
* impact on default version and version ordering
= Documentation Versions
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
CAUTION: this is a work in progress
NOTE: the following mainly applies to the Bonita Platform documentation part
image::images/DocToCloud-Architecture-BigPicture.png[]
== Bonita versions that are documented
For Bonita, the rule is the following one: +
We document the 4 currently supported Bonita versions, and **the 4 versions before**. +
== Impact on Algolia DocSearch
Each time a new version of a documented Bonitasoft project is released, this DocSearch configuration file has to be updated:
- The latest version has to be added to the projects to index
- The oldest version should be removed from the projects to index
-> It means that the DocSearch conf file should reflect this behavior.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment