Add documentation

Documentation/00_Index.md

@@ -0,0 +1,3 @@
+1. [User Interface](./Documentation/01_UserInterface.md)
+2. [Building Blocks: Objects, Agents and Tasks](./Documentation/02_BuildingBlocks.md)
+2. [Writing Custom Tasks](./Documentation/03_CustomTasks.md)

Documentation/01_UserInterface.md

@@ -0,0 +1,58 @@
+<div align="center">
+    <a href="./00_Index.md">Index</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./02_BuildingBlocks.md">2. Building Blocks &gt;</a>
+</div>
+
+---
+
+# 1. The User Interface
+
+Bitzer comes with several user interface components:
+1. Mixin node types to assign agents or intervals for automatic task creation
+2. The task reminder overlay on login into the backend
+3. The task overview module for editors to keep track of their work
+4. The task management module for administrators to manage task lifecycles
+
+> Hint: Additionally, there is a command controller available for task handling.
+> See ./flow help | grep bitzer
+
+## Scheduling tasks
+
+> Hint: For concrete examples, please see https://github.com/sitegeist/bitzer-review
+
+The default way of scheduling tasks is to configure a node type to use one of Bitzer's mixins.
+This way, individual nodes can be assigned to agents to perform tasks like review or translation
+in a certain interval.
+
+![Screenshot of Inspector Editor](inspector.png)
+
+Which tasks are to be scheduled is up to the concrete task implementations that Bitzer itself is the framework for.
+
+## The Task Reminder
+
+Upon login to the Neos backend, if there are scheduled tasks for the current user (as actor),
+an overlay is displayed that shows the open tasks and links to the task management module.
+
+![Screenshot of task reminder](screenshot.png)
+
+The most important function of PresentationObjects is to enforce the interface between domain and presentation layer.
+
+For a single component that interface is represented by an actual PHP interface. So let's start with that:
+
+## The Task Management Module
+
+All tasks to be performed are listed in the task management module.
+Here they can either be started or marked as complete. What happens when starting a task
+is up to the concrete task's implementation. A review task might just open the node for review
+while a translate task might create a variant of the node and display it.
+
+![Screenshot of task management module](module.png)
+
+---
+
+<div align="center">
+    <a href="./00_Index.md">Index</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./02_BuildingBlocks.md">2. Building Blocks &gt;</a>
+</div>

Documentation/02_BuildingBlocks.md

@@ -0,0 +1,67 @@
+<div align="center">
+<a href="./01_UserInterface.md">< 1. User Interface</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./00_Index.md">Index</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./03_CustomTasks.md">2. Writing custom tasks &gt;</a>
+</div>
+
+---
+
+# 2. Building Blocks
+
+The Bitzer building blocks are modeled using schema.org. The main entities are
+* Object (refers to a content repository node by its address)
+* Agent (can be a user or user group)
+* Task (https://schema.org/ScheduleAction)
+
+## Object
+
+Objects refer to nodes in the content repository, or rather their addresses to be precise.
+The node address concept is borrowed from the new event-sourced content repository
+and enables Bitzer to address nodes that do not yet exist.
+For example, a translation task can refer to creating a node variant that is still to be created via translation.
+> Hint: For custom development purposes, there is an object repository available.
+
+## Agent
+
+Agents can be all of Neos' backend users having Bitzer's agent role, as well as all roles that extend it.
+Thus, tasks can be assigned to a single user or a user group.
+> Hint: A data source for agents is available and used in the Setting.Agent mixin node type.
+> For custom development purposes, there is also an agent repository available.
+
+## Task
+
+Each task can be described by its properties:
+* it is scheduled for a certain **scheduledTime**
+* it has a certain **status**, e.g. active or completed (see https://schema.org/ActionStatusType)
+* it is to performed by a certain **agent**
+* it is about a certain **object**, in our case a node address
+* it has a **target** URI, which directs the agent to their user interface to perform the task
+
+Additionally, tasks have metadata:
+* a font awesome icon as an **image**
+* a **description**
+* arbitrary **properties** that might be relevant to the concrete task implementations
+
+> Hint: For custom development purposes, there is a task repository named "Schedule" available.
+
+Tasks themselves also have a lifecycle. They can be
+* initially scheduled
+* rescheduled to a different date
+* reassigned to a different agent
+* activated by an agent
+* completed by an agent
+* cancelled
+
+These actions are modelled as commands that are handed over to Bitzer, the central application service.
+
+---
+
+<div align="center">
+<a href="./01_UserInterface.md">< 1. User Interface</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./00_Index.md">Index</a>
+    &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+    <a href="./03_CustomTasks.md">2. Writing custom tasks &gt;</a>
+</div>

Documentation/03_CustomTasks.md

@@ -0,0 +1,60 @@
+<div align="center">
+    <a href="./02_BuildingBlocks.md">< 2. Building Blocks &gt;</a>
+        |
+    <a href="./00_Index.md">Index</a>
+</div>
+
+---
+
+# 3. Custom Tasks
+
+While some generic tasks like review or translation will be provided by Bitzer's own plugin packages,
+it is designed to allow for arbitrary tasks to be handled. There are a few steps to be taken for creating custom tasks.
+
+> Hint: To see custom tasks in action, please refer to https://github.com/sitegeist/bitzer-review
+
+## The task interface
+
+Each task must implement the provided `Sitegeist\Bitzer\Domain\Task\TaskInterface`.
+While most properties are just members passed on by the schedule, some are useful for customization.
+* getShortType should return a unique short name for the task
+* getImage should return a font awesome icon name that can be used by the Neos UI
+* getDescription can return a custom description, e.g. using the task's the properties array
+* getTarget should return the custom URI of the location the agent can perform the task
+
+## The task factories
+
+Each type of task can define its own factory. Those must implement `Sitegeist\Bitzer\Domain\Task\TaskFactoryInterface` and must be registered via config:
+```yaml
+Sitegeist:
+  Bitzer:
+    factories:
+      'Acme\Package\Domain\Task\MyTask\MyTask': 'Acme\Package\Domain\Task\MyTask\MyTaskFactory'
+```
+If no custom factory is required, Bitzer's `GenericTaskFactory` is used.
+
+## Handling tasks
+
+The life cycle of custom tasks is to be implemented by the respective package.
+Bitzer provides the same-named application service, repositories for tasks, objects and agents
+and the signal `taskActionStatusUpdated` emitted by the `Schedule`.
+What system events trigger automatic task generation is up to the specific use case.
+For manually managing tasks there is a backend module available as well as a command controller.
+
+## Testing
+
+Bitzer provides feature traits for Flow's behavioral test framework based on Behat.
+They can be used to
+* create and simulate testing agents
+* create testing objects
+* perform commands on tasks
+
+to enable custom implementations with ample testing capabilities
+
+---
+
+<div align="center">
+    <a href="./02_BuildingBlocks.md">< 2. Building Blocks &gt;</a>
+        |
+    <a href="./00_Index.md">Index</a>
+</div>

README.md

@@ -2,6 +2,27 @@
 
 > A content lifecycle task manager for Neos CMS
 
-![Screenshot of Task Reminder](./Docs/screenshot.png)
+![Screenshot of Task Reminder](./Documentation/screenshot.png)
 
-## Nothing to see here yet (except for the screenshot)!
+## The content life cycle
+
+From their initial creation until their final deletion, content repository nodes
+pass different stages of maturity. A news article might be first published as an abstract
+and then later on enriched with arbitrary media, then translated into a different language,
+updated with references to other articles and so on. If these changes are to be implemented
+in a planned way, we may model them as tasks.
+Bitzer provides a task model, an overview for editors for tasks assigned to them
+and an automation mechanism to generate new tasks, e.g. by defining a review date for a published news article.
+
+
+## Installation
+
+```
+composer require sitegeist/bitzer
+```
+
+## Documentation
+
+1. [User Interface](./Documentation/01_UserInterface.md)
+2. [Building Blocks: Objects, Agents and Tasks](./Documentation/02_BuildingBlocks.md)
+2. [Writing Custom Tasks](./Documentation/03_CustomTasks.md)