Roles for use in Documentation (Editor, Integrator, etc)

(Jacob Floyd) #1

So, here are some roles that the documentation for Neos needs to cover:

  • Editor
  • Integrator
  • System Administrator
  • Designer
  • Plugin Developer
  • Executives and Decision Makers (for more marketing-like higher-level explanations of what employees/contractors can accomplish in Neos/Flow)
  • Project Contributors and Team Members
    • Code Contributors
    • Docs Contributors
    • UI Contributors
    • ??? Contributors
    • Team Members

However, in thinking about the Integrator role, we’re having a hard time detangling Integrators and System Admins as well as Integrators and Designers.

For example, how much should the integrator documentation go into the Neos setup process including the setting up the database, the php environment, and whatnot? We could have a System Administrators guide that talked about several methods including Configuration Management (Chef/Ansible/etc), Docker, VM, Shared Hosting, etc. Some environments need the DB to be created before Neos can run its setup, while others will allow Neos to actually create the database. But, if we put all of that in a system’s administrator’s guide, do we need to include it in an Integrator’s guide? What’s the difference between Integrators and System Admins?

Then, there are a variety of methods for building templates for different sites. Templating is very much an integrator topic, until its not. When does it become a topic for designers? Would a templating tutorial that follows Atomic Design go in the Integrator Guide or a Designer Guide? What about when using something like Zurb Foundation? Or converting an HTML template (purchased somewhere random or provided by a designer) into a Fluid Template? Or what about when some sad soul is only given a PSD, and they need to create the appropriate Fluid templates from that? What goes in a guide for Deisgners, and what goes in a guide for Integrators?

Am I missing some important roles?

(Patrick Rodacker) #2

what about developers or authors who want to contribute? So, maybe one or two more roles like

  • development contributor
  • documentation contributor

(Jacob Floyd) #3

I just modified my OP to add some contributor categories. Some of that will end up on the Neos website I think. But, I wonder how much of it will make sense to keep in the docs in our main repository? I guess we’ll play it by ear and see where contributor and team stuff actually lives one written.

(Patrick Rodacker) #4

I know the integrator role is strongly related to the history of Neos growing within the TYPO3 community. I am just wondering if this applies to Neos as well or if this would be a Administrator & Developer role? I don’t want to do everything new, but I think we should allow thinking in all different directions and question the current situation. Imo this would just be reflected in the naming of documents / sections and some content structuring, but not in a kind of content refactoring :wink: