RFC: Scenario-based Recipes / How-to's

[nickwesselman]

It has become very clear that the Helix documentation should include some scenario-based narratives that give guidance on how to follow the practices and adhere to the core principles. Feature-to-Feature communication in particular (via unification in the Project layer, or abstraction/inversion in the Foundation layer) would seem to be a great place to start.

What other scenarios, patterns, etc. would be helpful to document in the form of recipes or how-to's?

[TwentyGotoTen]

Hey @nickwesselman. Along with trying out alternative solution structures, I think this is one of the key things that will drive greater adoption/acceptance of Helix.

I run Helix workshops for developers where I work, and have most success by using the following process with small, realistic examples of common tasks that you might perform on a Sitecore project.

1. Show a typical non-Helix implementation of code
2. Point out the problems with it, without directly referencing 'Helix principles'
3. Gradually work through fixing the issues, encouraging people to use common sense
4. Once the fix is complete, explain the underlying principles and how they align with what we just did

Here's an example codebase I use for a workshop on refactoring a custom link provider. I presented a simplified version of this at a recent user group

I recorded a talk for the virtual developer day on 'Helix Smells', where I discussed common things that go wrong on Helix projects. Maybe you can take a look at that to see if it provides any inspiration. The emphasis was on trying to arrive at a reasonable solution through common sense without having to bash people over the head with too much theory up front.

[dthunziker]

-F2F references via project layer
-F2F references via foundation layer
-Examples of referencing project templates from a rendering’s Datasource Template field within the feature layer
-Features that are specific to only one project for now and to eternity (where does it go?)
-Reusing controllers/renderings from a feature across multiple projects
-Seperating front end styles across Foundation/Feature/Project
-Seperating front end JS across Foundation/Feature/Project
-When and how to split out into multiple solutions
-Deploying via a single WDP, not 100
-Deploying to Azure PaaS
-Is a Helix solution tied to a Sitecore instance (1-two-1)?

[dsolovay]

I would add:

• NuGet modules vs all code in the solution, and when to use each appraoch (e.g. NuGet for widely used foundational code?)
• Considerations for deciding module boudaries, both synchronously (when breaking apart an initial build) and asynchronously, when adding features to an existing site. Narrative exampls could be very useful here.
• Starter kit scenarios. When to treat code as a modifiable template, and when to treate code as fixed but versionable. I can see situations where an in house accelerator would version foundation code (using NuGet or git moduels, as discussed above), but treat features as starting points. The different treatments would be driven by different reuse scenarios.

[alinulms]

I have encountered questions similar to

"Feature-to-Feature communication in particular (via unification in the Project layer, or abstraction/inversion in the Foundation layer) would seem to be a great place to start.".

If 2 features need to access the same code, say a repository, a service or similar then it makes sense to move the common functionality into Foundation.

However, regarding the second scenario, I have yet to figure out one and I would tend that if one feature must expose itself in another feature we might be looking at a design flaw. I'm not saying scenarios are not there but I can't think of one and I've never had to deal with one either.

[nickwesselman]

Definitely want to add some recipes/how-tos to Helix Docs, and I think anti-patterns and smells ala @TwentyGotoTen's content would be great too.

[nickwesselman]

Use case examples for F2F / Dependency Inversion recipes, raised by @markstiles:

• How to allow a Feature to display different content in a search result tile within a Search feature ?
• Feature-specific navigation functionality that needed to reuse fields or logic from existing site Navigation feature.