Where to put new material?

dsolovay commented 5 years ago

In sitecore/Helix.Docs#20, there is consensus on the need for more material on the foundational package principles. However, these are already discussed in some depth in the Architectural Principles section, and it would be difficult to add introductory material to this section. On the other hand, the material in the Introduction seems like it could benefit from a rethinking (see Sitecore/Helix.Docs#28). So, proposing the following approach:

Rewrite introduction. Scrap discussion of race cars and definitions, and address with a few paragraphs that speak to the reasons why standards for Sitecore architecture are needed, and explains why the Package Principles are a logical fit, but without discussing these in depth (so as to not submerge people in terms like "the granule of release" when they are just starting.
Add a lengthier section at the end, "Architectural Founadtions" or similar, that goes into the package principles, and perhaps SOLID in some depth, relating them to specific practices discussed earlier in the document.

This approach will allow a more detailed discussion of the principles, and will also reinforce the practices (e.g. interface templates, role of abstractions in foundation) as they will be placed in a theoretical context. This section 4 might have additional suporting material, such as references to current writings or source material, FAQs and so forth.

dsolovay commented 5 years ago

The relevant SOLID concepts are OCP, which you need to have a strong handle on to understand how the foundation can be abstract, extensible, and stable, and ISP, which is necessary to have a handle on inter-module communication. But the package principles will be the star of the show.

nickwesselman commented 5 years ago

Hey Dan, would you mind moving this issue to the original Helix.Docs repo instead of your fork? It can still be a new issue that references the RFC (i.e. start a new discussion about the Where/How vs the Why).

dsolovay commented 5 years ago

Sure thing. I guess I saw this as a place to brainstorm semi-privately, so I may fine tune this before moving it over, but I get the value of avoiding fracturing.

On Wed, Mar 27, 2019 at 6:49 AM Nick Wesselman notifications@github.com wrote:

Hey Dan, would you mind moving this issue to the original Helix.Docs repo instead of your fork? It can still be a new issue that references the RFC (i.e. start a new discussion about the Where/How vs the Why).

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/dsolovay/Helix.Docs/issues/1#issuecomment-477093215, or mute the thread https://github.com/notifications/unsubscribe-auth/AAqFfOJvGaBpGUi5vb6586rtUlw4zgJFks5va0zHgaJpZM4cAV0W .

dsolovay commented 5 years ago

Closing to keep discussions in main fork.

dsolovay / Helix.Docs

Where to put new material? #1