Add best practices to relevant sections in the guide

[adahms]

Some recommendations for modular documentation practices that would be good to share more broadly:

• When making a decision about structuring modules and assemblies, always favor simplicity and ease of maintenance.

• It is acceptable to either create multiple modules or split out pieces of content using conditions, but some deciding factors are as follows -

  • Two cases for conditional statements are fine, thirteen cases for conditional statements are not.
  • Some content duplication is acceptable in order to make content easier to manage
  • Some suggestions: 5-6 sentences, a few paragraphs, conditionally include a module

• Do not base conditions on context because it is hard to determine the exact context at the time of publication and because it can change without you knowing.

• Set the context attribute to something that is unlikely to change, and something that is very specific, so that you don't risk this variable crossing over with something else in another release.

[adahms]

@tradej - Raising this one for consideration based on the recent PoCs session. As you can see, I am borrowing some of your wording here, but not suggesting we need to keep this exact wording if we go ahead with this.

Opening for general comment.

[thatdocslady]

This feels related to the FAQ issue that I commented on here #3 .

Having a generic catch-all section for these types of things feels less useful than addressing them in-context. For example, documenting best practices for conditions in a module (or even a sub-heading in a broader concept module) inside the assembly that covers conditions might be more useful for the readers and won't require jumping around between various areas of the guide.

Being able to triage and distribute best practices and FAQs to their respective assemblies might be something we want to look into (are the GH issues used for this purpose too? Maybe it's worth creating some issue templates for RFEs for the guide, or leverage JIRA for this), and it might help address the need for more opinionated mod docs docs :)

[tradej]

@thatdocslady You raise a valid point.

Should I refile the points in the list as separate issues for inclusion in their respective sections, or do we want to transform this ticket into tracking addressing them specifically? cc @adahms

[thatdocslady]

Thanks @tradej! I guess there's nothing stopping us from resolving all the points in the same PR/issue, as long as the PR covers all the respective locations of the points. This might help fix the immediate needs in the guide and resolve this issue, and we can possibly open a new issue for thinking about long-term workflows for future requests of this type. WDYT?

[tradej]

Makes sense. @adahms, can you please modify this ticket to only cover the bullet-points instead of the best practices section? Thanks.

[adahms]

Hey @tradej - done and done!

I've kept it simple, so let me know if you'd prefer a more detailed overview.

[tradej]

Thanks, @adahms, it looks great. Can you please rename the ticket too, please? It's a bit confusing now because no section is being added.