How do we handle something like a "Best Practices" section, which might contain a combination of Procedure, Concept, and Reference information?

[IngridT1]

The OpenShift team is dealing with this issue for some content that they are currently working on. Here is a Google Docs version of the content, which is passworded: https://docs.google.com/document/d/1qgf6hd205X6jNSc7vCHlVr1IuKIVJBWTKz9UQBTKITI/edit#

Any thoughts or recommendations are welcome? @kalexand-rh , do you have anything to add?

[bhardesty]

From what I'm seeing, I would use concept modules for this type of content. If the guidelines/considerations are short, you could have a single concept module that lists each of the guidelines in a bulleted list or definition list.

Alternatively, you could put each guideline in a separate concept module (which is probably what I would do with the OpenShift content in the linked Google doc), and collect all of them in a "Guidlines for ..." assembly. That way each guidelines is capable of standing on its own, but collectively they're part of a larger planning-related user story (i.e. before doing x, review the guidelines). Depending on the overall architecture of the deliverable, you could even have a step or prereq in a separate procedure to review the guidelines (for example, if there was a "Creating an image" procedure, it could have a prereq or step to review the guidelines for creating images, which would link to the assembly/module that documents the guidelines).

[adahms]

I agree with @bhardesty - the content in that document looks like a collection of primarily concept modules. Just, concept modules that happen to be about best practices.

Interestingly, the 'DITA Best Practices' guide also contains best practices as admonitions inside existing topics. As the tooling becomes a little more free, maybe we can do something similar should the need arise.

[bobjohnsrh]

I have always treated best practices as conceptual information. Including procedure or reference information is usually more granular than is necessary for best practices.

In some best practices, I have pointed to procedures in the documentation, sometimes including recommendations for specific data to use or configurations to implement. But I have never documented a procedure as part of best practices, largely because users will not look in best practices for procedural information.

I can't remember a time I included reference information in best practices, or even considered doing so.

[adahms]

Thanks @bobjohnsrh!

@IngridT1 - Do the answers here provide enough backing to take a given direction, or are there any aspects it might be good to delve into deeper?

[adahms]

@IngridT1 - Conducting a review of older issues in this repo, and checking in to see if the above answers provide sufficient context, or whether you feel there is something else we can add to this.

Unless there are any objections, I'll close this issue as-is at the end of the week.

[IngridT1]

@adahms That's fine with me. I like the idea of considering Best Practices to be mainly conceptual material.

[adahms]

Thanks for the reply, @IngridT1!

I'll close this issue now, but this has been a good discussion and this thread will be a good of reference for us to come back to should we need to further the discussion at some stage again in the future.