How to write a clean troubleshooting section

This is how to create a troubleshooting:

  • The title should be "Troubleshooting" and not "Troubleshoot"

  • "Symptom": describes what the user experiences

  • "Cause": describes the diagnosis from Bonita perspective

  • "Possible solutions" (if there is still uncertainty about its efficiency depending on the user’s context) or "Solutions" (if we know for sure it works): a step-by-step guidance to lead the user to success.

  • Depending on the position of the troubleshooting section in the page, you can:

    • Add a separator above the "Troubleshooting" title of the section, if this section appears at the bottom of the page and addresses the whole content of the page

    • Adapt the level of the header; it should be the same than the content it is related to

Do not add extra lines above and below the section content. The title already provides a separator between the title and the content.

Troubleshooting

See code example

[.troubleshooting-title]
== Troubleshooting

Any troubleshooting section example

I can’t wake up in the morning, 9AM is too early for me!!!

When my alarm goes off, I turn it off and go right back to sleep.

Potential cause This is probably because I often go to bed at 3AM :'(

Possible solution I should just stop watching netflix for hours…​

Click to see code example 
[.troubleshooting-section]
--
[.symptom]
I can't wake up in the morning, 9AM is too early for me!!!

[.symptom-description]
When my alarm goes off, I turn it off and go right back to sleep.

[.cause]#Potential cause#
This is probably because I often go to bed at 3AM :'(

[.solution]#Possible solution#
I should just stop watching netflix for hours...
--

My code block is not display on troubleshooting solution section

When i write some block code example, the display is not correct

Cause This is potentially because i miss an ending character after code block.

Possible solution

@BonitaTests
class ProcessIT {

    @Test
    void should_retrieve_user(BonitaTestToolkit toolkit) {
        User user = toolkit.getUser("walter.bates");
        ...
    }
}
Click to see code example 
[.troubleshooting-section]
--
[.symptom]
My code block is not displayed in the troubleshooting solution section

[.symptom-description]
When i write some block code examples, the display is not correct

[.cause]#Cause#
This is potentially because I am missing an end character after the code block.

[.solution]#Possible solution#
[source,java]
----
@BonitaTests
class ProcessIT {

    @Test
    void should_retrieve_user(BonitaTestToolkit toolkit) {
        User user = toolkit.getUser("walter.bates");
        ...
    }
}
----
--

I don’t want display potential cause as title

When i sure about the cause, I want to remove potential on title

Cause No doubt about the cause

Possible solution Just write Cause as title

Click to see code example 
[.troubleshooting-section]
--
[.symptom]
I don't want display potential cause as title

[.symptom-description]
When i sure about the cause, I want to remove potential on title

[.cause]#Cause#
This is probably because I often go to bed at 3AM :'(

[.solution]#Possible solution#
Just write `Cause` as title
--

HTTP/1.1 401 Unauthorized

Cause The logged user has no permission to access the resources.

Possible solution

  1. Make sure that the cookies transferred are the ones generated during the last sucessfull login call

  2. If one of the PUT, DELETE or POST method is used, make sure that the X-Bonita-API-Token header is included

  3. If the X-Bonita-API-Token header is included, make sure that the value is the same as the one of the cookie generated during the last login

  4. Maybe a logout was issued or the session has expired; try to log in again, and re-run the request with the new cookies and the new value for the X-Bonita-API-Token header.

Click to see code example 
[.troubleshooting-section]
--
[.symptom]
HTTP/1.1 401 Unauthorized

[.cause]#Cause#
The logged user has no permission to access the resources.

[.solution]#Possible solution#

1. Make sure that the cookies transferred are the ones generated during the last sucessfull login call

2. If one of the PUT, DELETE or POST method is used, make sure that the X-Bonita-API-Token header is included

3. If the X-Bonita-API-Token header is included, make sure that the value is the same as the one of the cookie generated during the last login

4. Maybe a logout was issued or the session has expired; try to log in again, and re-run the request with the new cookies and the new value for the X-Bonita-API-Token header.
--

For theme tests only

Here we check the rendering depending on the title level.

Troubleshooting 2

Troubleshooting 2 Without icon

Troubleshooting 3

Troubleshooting 3 Without icon

Troubleshooting 4

I can’t wake up in the morning, 9AM is too early for me!!!

Here enter a symptom description

Potential cause This is probably because I often go to bed at 3AM :'(

Possible solution I should just stop watching netflix for hours…​

@BonitaTests
class ProcessIT {

    @Test
    void should_retrieve_user(BonitaTestToolkit toolkit) {
        User user = toolkit.getUser("walter.bates");
        ...
    }
}