What documentation do Neos Integrators need?


(Jacob Floyd) #1

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 :smile:). So, we could have the same basic structure as the Flow Definitive Guide with 3 major sections (ignoring appendixes and deployment guide for now):

  1. Introduction and Fundamentals
  2. Getting Started
  3. Manual

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
    the “Publish Everywhere” part of COPE: Rendering in Fluid/TypoScript, Inside TypoScript, Eel/FlowQuery/Fizzle, Adjusting Neos Output, Content Cache, JavaScript and Neos Backend

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?


(Dominique Feyer) #2

Meteor did a really good job for documentation (http://docs.meteor.com/#/basic/) and Laravel too (http://laravel.com/docs/5.0), I think it’s a good idea to pick some idea on both projet.


(Patrick Rodacker) #3

I really like the Meteor tutorial they provide and the look and feel of it offers a nice learning experience. From Laravel we could pick some stuff for the Flow docs I guess, but imo this will not fit for the Neos user roles like the here focussed integrators.

@cognifloyd: would the step-by-step tutorial be Ch2 or should this be a level higher like YourFirstSite Tutorial ?


(Martin Ficzel) #4

I’d like to see an appendix section in the integrator docs aswell. The Fluid-Viewhelper-Reference and the Eel-Helper-References from all packages could be available there.