Explore ways to document troubleshooting steps

[laubai]

Some options:

Option 1: Add a .Troubleshooting section Add a ".Troubleshooting" heading to the module/assembly (between the procedure and the verification? between verification and additional resources?) and document troubleshooting suggestions as bullets under this heading, e.g.

.Troubleshooting
* If you see error A:
.. Perform solution A step 1
.. Perform solution A step 2
* If you see error B, perform the single-step solution B.

Cons:

• may clutter an otherwise clean procedure if there are many possible issues
• duplication of effort is likely if the same steps are used to troubleshoot problems in multiple procedures

Option 2: Create troubleshooting modules or assemblies based on... Create a module or assembly that covers troubleshooting for this particular action attempted by a user, or this particular type of user, or this particular type of error... lots of ways to slice this so that it is useful, e.g.

• Common problems during installation
• 403: Forbidden errors
• Common problems for database administrators

Structure these in some consistent way, e.g.

= Brief description
Symptoms: You see a 403: Forbidden error when you log in to the service.
Cause:  Your user name is not in the allowed users group.
Solution: Ask an administrator to add you to the allowed users group using the instructions at <link>

As an idealistic pipe dream, I would like a solution that lets us: (a) create a module as in option 2, and (b) refer to the abstract of the module in option 2 from our troubleshooting section (or even from within the step in which the problem will occur) in option 1.

[sterobin]

@laubai Excellent ideas. For me, the .Troubleshooting label option is most consistent with how we already handle .Verification etc., so I think at the moment that would be my vote. And that's even given the valid cons you provide, which imo also apply to .Verification sections that are already sanctioned. Will see what others think.

[rkratky]

I'd go with @laubai's option no. 2, provided we continue using the existing procedure templates for this. Troubleshooting, after all, is a specific kind of a procedure.

I'd leave it to the writer's assessment to decide whether to use one procedure module for a bunch of very simple troubleshooting tips (a collection of short actions), or to have an assembly that would include a number of stand-alone troubleshooting procedures (if more complex). The usual rule-of-thumb for determining whether something is a module or not would apply (if it can stand on its own and be potentially reused, it's a module).

[thatdocslady]

I can see value in both options, and actually we could consider something similar to the way we give writers the option of adding .Verification in the procedure itself, or if the procedure is too big it can be its own module (which I've also seen). I've written "Testing deployment xyz" procedures before, and it's especially useful in cases where the troubleshooting encompasses multiple procedures or an end-to-end story (I link to it from the .Additional Resources section). On the other hand, sometimes you just have one or two bullet points, in which case .Troubleshooting can be sufficient. Lots to think about :)

[mjahoda]

I would not make the FCC templates and rules more complicated. I think that even very challenging troubleshooting cases (for example, [1]) can be covered by using some combination of procedure and reference modules ([2]). Of course, it would be nice to have a convenient option to include such a diagram [1] directly in our product docs, or even better, its interactive form, but it is for a different discussion.

[1] https://www.dropbox.com/s/wlh2b3ymyrwk6uk/big-chart.png?n=60513339&oref=e

[2] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/troubleshooting-problems-related-to-selinux_using-selinux

[emmurphy1]

Revisiting this issue in light of the recent announcement about adopting the IBM publishing framework and in consideration of other requirements coming out of the work around content types, perhaps we should consider expanding the templates to include a trouble-shooting assembly. There are other content types that we could consider as well, for example, tutorials. Our modules do not fully serve these content types.

[thatdocslady]

FWIW, at the OSP team level we just completed an initiative to document guidelines on troubleshooting content, and during the brainstorming sessions we realized that we might not be able to provide templates for it because it can take up multiple forms (i.e. a section in a module, a standalone module, a chapter, etc).

I'm in the process of drafting a blog post for CCS on the initiative where I'll be describing what we did and inviting other teams to give feedback and share their troubleshooting stories, but in the meantime you can look at this Confluence page and see if there's anything we can use in our group?

[Deleted link because I realized it's internal, will post it in Slack/GChat for now]