Provide a way to avoid duplicating "Bonita editions" admonitions in all Enterprise edition pages

tbouffard commented 2 years ago

Today, the wording is duplicated in all pages. This makes hard to modify the message and strange for external contributors.

See discussions that occurred in https://github.com/bonitasoft/bonita-doc/pull/1534. Someone wanted to update the messaging because he said Text updates to reflect only Enterprise edition as of 2021.1. Please read all comments of the PR to get the whole context.

If we decide to implement a solution, we should choose carefully the version of the document where we apply the change.

There are mentions to the Enterprise edition in Bonita 7.7

https://documentation.bonitasoft.com/bonita/7.7/cluster-administration

Messages of the edition notices in pages today

All editions

This is the most common notice we have: In Teamwork, Efficiency, Performance and Enterprise editions (sometimes not in this order like in https://github.com/bonitasoft/bonita-doc/blob/048664655e8c6bb5b2a128e93680d4e282fe69f4/modules/best-practices/pages/project-documentation-generation.adoc 😢)

https://github.com/bonitasoft/bonita-doc/pull/1881#pullrequestreview-852807600 describes the recent usage of For Subscription editions only.

Performance and Efficiency

https://documentation.bonitasoft.com/bonita/2021.2/identity/bdm-access-control

Performance only

https://github.com/bonitasoft/bonita-doc/blob/530204702d936448c9eebba61dab73615bbadf33/modules/runtime/pages/overview-of-bonita-bpm-in-a-cluster.adoc https://documentation.bonitasoft.com/bonita/2021.2/runtime/overview-of-bonita-bpm-in-a-cluster

Position of the edition notices in pages today

It is generally on top of the page or just under the 1st paragraph

Special cases today

After paragraphs and warnings + custom message

https://documentation.bonitasoft.com/bonita/7.10/purge-tool https://github.com/bonitasoft/bonita-doc/blob/9d4f0689908ba9ac5962b2deaeed83f89729c5ce/modules/ROOT/pages/purge-tool.adoc

important: it contains a custom message in addition to the editions notice

In paragraph titles in this case, a regular admonition notice will be more convenient

https://documentation.bonitasoft.com/bonita/2021.2/api/form-api#_update_a_form_mapping_efficiency_performance_and_enterprise_editions

In several paragraph of the same page

https://documentation.bonitasoft.com/bonita/2021.2/software-extensibility/software-extensibility https://github.com/bonitasoft/bonita-doc/blob/048664655e8c6bb5b2a128e93680d4e282fe69f4/modules/software-extensibility/pages/software-extensibility.adoc

Others

See proposed changes in the multi-tenancy page

Proposals

Feel free to update the description or add comments with more suggestions or agree/disagree with proposals

Proposal 1: Define an AsciiDoc attribute in the page and in the theme, generate the admonition accordingly

For instance: bonita-edition: <> / default: community (no admonition)

if Enterprise, put Enterprise
otherwise, the minimal subscription edition must be set, for instance Efficiency

cons

need doc for the enumeration values
not flexible for positioning. Not possible except by setting more attributes to manage position on top, after the 1st paragraph or in the middle of the page

Proposal 2: use custom Asciidoc syntax

Provide a custom AsciiDoc block/syntax that can be put everywhere and the thee interprets it to generated the admonition. For instance {BonitaLicense=efficiency}

pros

options to select the edition
can be placed everywhere

cons

custom
need a theme update

Proposal 3: use Antora partials

https://docs.antora.org/antora/2.3/partials-directory/ https://docs.antora.org/antora/2.3/page/partials-and-content-snippets/

pros

define the partial directly in the repository content
can create a partial file for each use case
use it as include, so it can be easily placed everywhere
no dependency on theme, so can be started immediately
we can have different content per version i.e. we are able to change the messaging depending of the Bonita version

cons

duplication in versions/branches

vbotnari12 commented 2 years ago

Proposal: have a documentation task force to handle this topic.

NathalieC commented 2 years ago

We want to keep in mind that:

This information can be added at any level and position in a doc page
Everyone can contribute pages and content to the documentation (the more we make it specific and "code-like", the less contributors will manage it right)

My first thought is that we should stick to the regular "info" admonition (very simple to implement), and communicate on the right content to provide. If one of the proposals made by Thomas seems even simpler to implement, then I think we could manage to make it work most of the time by a broad and repeated communication internally, add it to the Contribution guide, and get ready to make corrections for external contributions (same for Troubleshooting, I know). Any chance we can have demos of all three proposals sometime ?

About the content: To me:

Nothing if the feature is Community
"For Subscription editions only" if available in Teamwork, Efficiency, Performance, and Enterprise editions
"For Efficiency, Performance, and Enterprise editions only" if Subscription but not Teamwork
"For Performance and Enterprise editions only" if any
"For Enterprise edition only" if any

benjaminParisel commented 2 years ago

We decided to not implement a specific templating for the edition-only messages. We hope the reviewer will keep in mind the format of this message.

[x] Add in contribute guide example ( Info Admonition, edition in right order teamwork, efficiency, performance, and enterprise). #449

tbouffard commented 2 years ago

I guess the best place to store the information is in the documentation theme. If we go that way, I suggest we reorganize the left menu by adding a Guides news sections on top of the Examples This would highlight guides like monitoring, bonita licenses and we could rename Examples into something else to state that this is about the syntax only In addition, we could add a specific cards in the home page to link to the new "bonita licenses" guide.

Current left menu

vbotnari12 commented 1 year ago

Can I know why are you handling this battle on your own? :) For your information, if I was not curious and meddling everywhere, I would NOT have been aware of the decision taken regarding edition admonitions. We sure need to find a way to share this kind of information...

tbouffard commented 1 year ago

The decision as been taken in June, 15th and is described in https://github.com/bonitasoft/bonita-documentation-theme/issues/129#issuecomment-1260820442 It is missing that @NathalieC took the decision (she was in charge of managing the documentation content) after discussions with us. We didn't take it alone.

tbouffard commented 1 year ago

https://github.com/bonitasoft/bonita-documentation-site/pull/449 includes guidance in the Contributing Guide. Work has to be done in the bonita-doc repository. See https://github.com/bonitasoft/bonita-doc/pull/2182

So closing.

bonitasoft / bonita-documentation-theme