feat: start adding user and admin documentation for Collectives

admin_manual/collectives/index.rst

@@ -0,0 +1,100 @@
+===========
+Collectives
+===========
+
+Runtime Dependencies
+--------------------
+
+Collectives requires the following apps to be enabled. They're all shipped and enabled by default with
+the Nextcloud server installation:
+
+* **Teams** (with Nextcloud >= 29) or **Circles** (with Nextcloud <= 28)
+* **Text**
+* **Viewer**
+* **files_versions**
+
+Collectives and `group_everyone`
+--------------------------------
+
+When using the `group_everyone app`_, existing users will not see collectives with the "everyone" group
+as member. The group members need to be synced once in the circles app: ``occ circles:sync --groups``
+
+.. _group_everyone app: https://github.com/icewind1991/group_everyone/
+
+This only needs to be done once. New users that got created after the app was enabled will see
+the collectives straight away.
+
+Collectives and guest users
+---------------------------
+
+In order to allow guest users (as provided by the `guests app`_ to access collectives, add the Collectives
+and Teams apps to the list of enabled apps for guest users in admin settings.
+
+.. _guests app: https://github.com/nextcloud/guests/
+
+Please note that this enables guest users to create new collectives.
+
+Public shares
+-------------
+
+WebDAV access to public shares must not be disabled (i.e. it must be enabled) for publicly shared
+collectives to work. Please make sure that the following admin option is enabled:
+"Allow users on this server to send shares to other servers (This option also enables WebDAV access to public shares)"
+under "Sharing -> Federated Cloud Sharing".
+
+Configuration
+-------------
+
+Initial Content for new collectives
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's possible to create custom content for new collectives by putting files in the app skeleton directory
+at ``data/app_<INSTANCE_ID>/collectives/skeleton``. New collectives start with the contents of this directory.
+
+Create a ``Readme.md`` file to change the landing page that is opened automatically when entering a collective.
+
+If the skeleton directory doesn't contain a ``Readme.md``, the default landing page from
+``apps/collectives/skeleton/Readme.md`` will be copied into the collectives directory instead.
+
+Allow for groups in your collectives
+------------------------------------
+
+You can configure the Teams app to allow adding groups to teams. Since the Collectives app relies on the
+Teams app for user management, this also allows adding entire groups to collectives.
+
+Keep in mind thought that in contrast to teams, groups can only be managed by server admins.
+
+Importing existing data
+-----------------------
+
+Import existing Markdown files is possible with the occ command ``occ collectives:import:markdown``.
+
+The command imports Markdown files from a directory as new pages into a collective. After
+importing all files, it processes relative links and referenced local attachments in the
+Markdown files. It tries to fix links to other pages and uploads referenced attachments when
+the source file is found in the import directory.
+
+Please beware that the command is memory intensive. When importing a directory with many
+Markdown files, make sure to increase the PHP memory limit accordingly:
+
+.. code-block:: shell
+
+   php -d memory_limit=<X>G ./occ collectives:import:markdown -c <collectiveId> -u <userId> /path/to/markdown/files
+
+Importing from Dokuwiki
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Markdown directory import command (see above) supports to import Markdown files
+generated from a Dokuwiki instance and tries to fix relative links to other pages and
+upload referenced attachments.
+
+Importing is tested with Markdown files generated with the `Dokuwiki2Markdown`_ tool.
+
+.. _Dokuwiki2Markdown: https://github.com/mm503/Dokuwiki2Markdown
+
+Here's an example how to import from a Dokuwiki instance:
+
+.. code-block:: shell
+
+   /path/to/doku2md.py -d /path/to/dokuwiki/data/pages -T
+   php -d memory_limit=2G ./occ collectives:import:markdown -c 123 -u alice /path/to/dokuwiki/data/pages

admin_manual/contents.rst

@@ -63,6 +63,11 @@ Table of contents
 
     office/index
 
+.. toctree::
+    :caption: Collectives
+
+    collectives/index
+
 .. toctree::
     :caption: Maintenance
 

user_manual/collectives/getting_started.rst

@@ -0,0 +1,57 @@
+===============
+Getting started
+===============
+
+Think of Collectives as your space to take notes together and collaborate online.
+You and your peers can write documents collaboratively and structure your shared
+knowledge. You can even embed task boards, whiteboards and calendars. Collectives
+emphasizes horizontal and non-hierarchical workflows.
+
+.. image:: images/screenshot.png
+
+Why use Collectives?
+--------------------
+
+* You need a tool to collaborate, cowork or organize with others.
+* You want all your shared knowledge in one place.
+* You want a quick and easy overview of your pages and subpages.
+* You want to share parts of the knowledge with external people.
+* You already use Nextcloud.
+
+First steps
+-----------
+
+You will create your first collective with two pages and a link from one to the other. It
+expects that you open Collectives in a desktop browser (i.e. not on mobile).
+
+1. Select the Collectives app in the app menu on the top:
+
+   .. image:: images/open_app.png
+      :width: 100px
+2. Click on “New collective”.
+3. Enter the name ``My first collective`` and choose an emoji (or keep the preselected one).
+4. Select “Create without members”. We’ll learn how to add other members later.
+5. In the page list on the left, click the ➕ button next to the landing page. Congratulations,
+   you just created a first page in your collective. 🎉
+6. Give the page a title by typing ``My first page``.
+7. Now press :kbd:`Enter` and the cursor will jump to the (still empty) page content.
+8. Type ``## My first heading`` to insert a second-level heading. Alternatively you can open
+   the headings menu in the editor toolbar, select “Heading 2” and then type ``My first heading``.
+   You just learned that there’s more than way to format text 🎉
+9. Create a subpage of “My first page” by clicking the ➕ button next to “My first page” in the
+   page sidebar. The button will only appear once you hover the mouse cursor over the entry in
+   the page list.
+10. Give the subpage a title by typing “My subpage”.
+11. Add a link from to the first page by opening the 🔗 link menu in the editor toolbar and
+    selecting “Link to page”. A dialogue to select the page will open. Type ``first`` in the
+    search field and “My first page” will appear. Click on it and it will be added as a link
+    preview to the subpage.
+
+Congratulations, you learned two important basics when working with Collectives: how to create
+and link between pages and how to format content in a page.
+
+What's next
+-----------
+
+* To learn how to use Collectives in your team, see :doc:`onboard_your_team`.
+* For an overview over features, see here.

user_manual/collectives/index.rst

@@ -0,0 +1,10 @@
+===========
+Collectives
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   getting_started
+   onboard_your_team
+   markdown_files

user_manual/collectives/markdown_files.rst

@@ -0,0 +1,12 @@
+==============
+Markdown files
+==============
+
+The pages of your collectives are stored in Markdown files. You can access them via the Files app.
+Per default, the folder is hidden as it's called ``.Collectives`` (or a translated version of it).
+To access the hidden folder, enable "Show hidden files" in the Files app settings.
+
+You can also change the name of the folder in the Collectives app settings. The setting is located in
+the Collectives app at the bottom of the collectives list. If you want the folder to be visible
+permanently without showing other hidden files, set the folder setting to a name without leading dot
+(e.g. ``Collectives``).

user_manual/collectives/onboard_your_team.rst

@@ -0,0 +1,40 @@
+========================
+How to onboard your team
+========================
+
+Our first project: Introductions
+--------------------------------
+
+Step 1: Create an “Introductions” parent page 📃
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Click on the ➕ button next to the collective name in the sidebar on the left hand side of Collectives.
+2. A new page is created. We can use this page as a parent page for our introductions! Let's fill it
+   with some nice introductory words for visitors and give it the title ``Introductions``.
+
+Step 2: Create an “Introduction”-template together 👥
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. It can be nice and more accessible, when all introductions follow the same format! Everyone should add
+   a picture, a brief description and answer what they like about collective organizing. Collectives
+   makes this very easy. We quickly create a template with exactly this content, so that everyone who
+   onboards can answer easily.
+2. Click the … button next to your collective. Choose "Manage templates", then "Add a template".
+   Collectives now adds a page for you to fill, which later can be easily and accessibly copied for
+   everyone who wants to create an introduction.
+3. Give your template the title ``Introduction``. Now add your fields as simple text to your document -
+   don't forget to decide on them collectively! By pressing on the Tt button in the formatting toolbar,
+   you can format your new text as headings!
+4. When you're finished, just press the X in the top right corner - your template will be automatically
+   saved and you should be back in your template manager.
+5. Let’s add a fun emoji for our new template last. Click the … button next to your new template and
+   click choose emoji…. Afterwards you can close the template manager.
+
+Step 3: Everyone creates their own! 💫
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. This is where the magic happens 🪄! Everyone on their own computers now! Click the ➕ button next to
+   your "Introductions" page that we created in step one. Select the "Introductions" template. Title
+   the page with your name or nick and fill out the fields your decided on!
+2. Wow! We just quickly created a cohesive und unifying "Introductions" page in our collective. Becoming
+   part of your collective will be much less scary now for new members! Congratulations! 🎉

user_manual/contents.rst

@@ -12,7 +12,8 @@ Table of contents
     activity
     files/index
     groupware/index
-    talk/index 
+    talk/index
+    collectives/index
     desktop/index
     userpreferences
     universal_access