As I’m looking at the miscellaneous current chapters in The Integrator’s Guide and the recommended content here in the Neos Integration Guidelines, I think maybe it’s all one guide: A Definitive Neos Guide for Integrators (the name needs work ). So, we could have the same basic structure as the Flow Definitive Guide with 3 major sections (ignoring appendixes and deployment guide for now):
- Introduction and Fundamentals
- Getting Started
In (1) Introduction and Fundamentals, cover the general design principles that would be especially helpful for an integrator to learn / keep in mind. (See General Things in the doc where we’re brainstorming Neos Integration Guidelines. Thanks for starting that, @dimaip!)
In (2) Getting Started, demonstrate a basic, best-practices way to integrate a site in Neos. We’ve started brainstorming what might go here in a google doc. Some notes/admonitions can point out several places where there are alternative methods, and link to something in the Manual chapter that goes over the alternative approaches. I imagine that this would be a fairly in-depth Getting Started guide with one page per major topic (like Flow’s guide does).
Then, we can use section (2) as the basis for a Neos Quickstart Guide similar to Flow’s Quickstart Guide that is just one “page” (something that might be long, but reasonably scrollable). In the current Getting Started for Neos, we currently have Installation and UI Basics. What if that had an installation chapter and then the one-page quickstart guide itself could be another chapter that assumes you already have it installed.
In (3) Manual, include a lot of the more in-depth reference materials about the CR/TypoScript/etc. I’m thinking of dividing this chapter into three parts to highlight COPE principles (Create Once Publish Everywhere): Content Inputs, Content Organization, and Content Outputs. Or perhaps we would have one section for Create Once (including Inputs and Organization) and another on Publish Everywhere (Outputs). I imagine that this stuff will expand quite a bit as we add more COPE-specific features.
- Content Inputs
the “Create Once” part of COPE: Media Package, DataSources, Resources…
- Content Organization
the Content Repository stuff: Content Structure, Custom Content Elements, NodeType Constraints, Dimensions, …
- Content Outputs
That would mean we’d have the following docs for integrators:
- Quickstart Guide for Integrators
- a one-page section in “Getting Started with Neos” which summarizes Ch2 of the Integrator’s Guide)
- Integrator’s Definitive Guide to Neos (combining Neos Integrator Guidelines and Integrator Guide)
- Ch1: Intro/Fundamentals
- Ch2: Getting Started
- An indepth guide through the process of integrating a website that includes Guidelines/best practices throughout (perhaps as note/admonition boxes).
- Ch3: Manual
- More component-specific reference material.
- Integrator’s Cookbook
- No change for now
Would the combined Integrator’s Definitive Guide to Neos (or whatever we call it) meet the needs of both “Integrator Guide” and “Neos Integration Guidelines”? Could we combine them like this? Would this structure of Integrator documentation make sense?