[TASK] Update documentation template to latest version (FriendsOfTYPO…

…3#280)

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/ChangeLog/Index.rst

@@ -1,16 +1,12 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
 .. include:: ../Includes.txt
 
-
 .. _changelog:
 
-ChangeLog
-=========
+==========
+Change log
+==========
+
+Version 1.0.0
+-------------
 
-Providing a change log chapter is optional. You can also refer
-users to the ChangeLog file inside the extension or to some repository's
-commit listing.
+Use this chapter to inform users of your extension about changes you made with each released version.

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Configuration/Index.rst

@@ -1,26 +1,22 @@
-.. include:: ../Includes.txt
-
+.. include:: ../Includes.txt
 
 .. _configuration:
 
 =============
 Configuration
 =============
 
-Target group: **Developers, Integrators**
-
-How is the extension configured? Aim to provide simple instructions detailing
-how the extension is configured. Always assume that the user has no prior experience
-of using your extension.
-
-Try and provide a typical use case for your extension and detail each of the
-steps required to get the extension running.
+How is the extension configured?
+Aim to provide simple instructions detailing how the extension is configured.
+Always assume that the user has no prior experience of using the extension.
 
+Try and provide a typical use case for your extension
+and detail each of the steps required to get the extension running.
 
 Typical Example
 ===============
 
-- Do we need to include a static template?
+- Does the integrator need to include a static template?
 - For example add a code snippet with comments
 
 Minimal example of TypoScript:
@@ -43,12 +39,12 @@ Minimal example of TypoScript:
 TypoScript Reference
 ====================
 
-When detailing data types or standard TypoScript
-features, don't hesitate to cross-link to the TypoScript
-Reference.
+Possible subsections: Reference of TypoScript options.
+The construct below show the recommended structure for TypoScript properties listing and description.
+
+When detailing data types or standard TypoScript features,
+don't hesitate to cross-link to the TypoScript Reference as shown below.
 
-Information about how to use cross-references:
-https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/Hyperlinks.html
+See :ref:`h2document:how-to-document-hyperlinks` for information about how to use cross-references.
 
 See the :file:`Settings.cfg` file for the declaration of cross-linking keys.
-You can add more keys besides tsref.

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Developer/Index.rst

@@ -1,37 +1,15 @@
-.. include:: ../Includes.txt
-
+.. include:: ../Includes.txt
 
 .. _developer:
 
 ================
 Developer Corner
 ================
 
-Target group: **Developers**
-
-This is your opportunity to pass on information to other developers who may be using your extension.
-
 Use this section to provide examples of code or detail any information that would be deemed relevant to a developer.
 
-You may wish to explain how a certain feature was implemented or detail any changes that might of been
-made to the extension.
-
-.. _developer-hooks:
+For example explain how a certain feature was implemented.
 
-Hooks
-=====
-
-Possible hook examples. Input parameters are:
-
-+----------------+---------------+---------------------------------+
-| Parameter      | Data type     | Description                     |
-+================+===============+=================================+
-| $table         | string        | Name of the table               |
-+----------------+---------------+---------------------------------+
-| $field         | string        | Name of the field               |
-+----------------+---------------+---------------------------------+
-
-Use parameter :code:`$table` to retrieve the table name...
 
 .. _developer-api:
 
@@ -57,4 +35,4 @@ or some other language:
       function () {
          doStuff();
       }
-   );
+   );

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Editor/Index.rst

@@ -0,0 +1,50 @@
+.. include:: ../Includes.txt
+
+.. _for-editors:
+
+===========
+For Editors
+===========
+
+How to use the extension from the perspective of an editor.
+
+Think of common tasks that an editor is likely to perform:
+
+- How do they complete them?
+- What problems are they likely to encounter?
+- What access do they require?
+- What configuration options are available to them?
+
+One example could be adding a frontend plugin to a page and then configuring it.
+
+Language should be non-technical, aim to avoid using acronyms where possible.
+
+Be mindful that editors typically don't have administrative access to the installation.
+
+.. tip::
+
+   Take a break from time to time.
+
+Admonitions should be used to warn the users about potential pitfalls.
+Attract their attention to important elements,
+or add some notes for for information (further reading, for example).
+
+Do not overuse admonitions like notes, important, etc.!
+
+Provide screenshots as needed for making things clear.
+When creating screenshots, try using the Official Introduction Package.
+
+.. figure:: ../Images/UserManual/BackendView.png
+   :class: with-shadow
+   :alt: Backend view
+
+   Default Backend view (caption of the image)
+
+Do not use huge full-screen images, unless it is necessary and serves a good purpose.
+
+.. _editor-faq:
+
+FAQ
+===
+
+Possible subsection: FAQ

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Includes.txt

@@ -1,40 +1,17 @@
 .. This is 'Includes.txt'. It is included at the very top of each and
    every ReST source file in THIS documentation project (= manual).
 
-.. This files lives at
-   https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Includes.txt
-   Version: 2018-10-16
-
-.. More information about this file:
-   https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#includes-txt
-
-.. Define some additional textroles
-   See: https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html
-
-
-.. ---------
-.. textroles
-.. ---------
-
 .. role:: aspect (emphasis)
 .. role:: html(code)
 .. role:: js(code)
 .. role:: php(code)
-.. role:: rst(code)
 .. role:: sep (strong)
+.. role:: sql(code)
 .. role:: typoscript(code)
+.. role:: yaml(code)
 
 .. role:: ts(typoscript)
    :class: typoscript
 
-.. role:: yaml(code)
-
 .. default-role:: code
-
-.. ---------
-.. highlight
-.. ---------
-
-.. By default, code blocks are php
-
-.. highlight:: php
+.. highlight:: php

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Index.rstt

@@ -1,101 +1,67 @@
-.. ---------------------------------------------------------------
-   This is the start file. It gets displayed as first page
-   https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/GeneralConventions/DirectoryFilenames.html#supported-filenames-and-formats
-   ---------------------------------------------------------------
-
-.. ---------------------------------------------------------------
-   More information about creating an extension manual:
-   https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/CreateWithExtensionBuilder.html
-   ---------------------------------------------------------------
-
-.. ---------------------------------------------------------------
-   comments start with 2 dots and a blank
-   they can continue on the next line
-   ---------------------------------------------------------------
-
-.. ---------------------------------------------------------------
-   every .rst file should include Includes.txt
-   use correct path!
-   ---------------------------------------------------------------
+.. every .rst file should include Includes.txt
+.. use correct path!
 
 .. include:: Includes.txt
 
-.. ---------------------------------------------------------------
-   Every manual should have a start label for cross-referencing to
-   start page. Do not remove this!
-   ---------------------------------------------------------------
+.. Every manual should have a start label for cross-referencing to
+.. start page. Do not remove this!
 
 .. _start:
 
-.. ---------------------------------------------------------------
-   This is the doctitle
-   ---------------------------------------------------------------
-
 =============================================================
 {extension.name}
 =============================================================
 
-:Extension Key:
-    {extension.extensionKey}
-
 :Version:
-    |release|
+   |release|
 
 :Language:
-    en
+   en
 
-:Copyright:
-    <f:format.date format="Y">NOW</f:format.date>
-
-:Author:
-    <f:for each="{extension.persons}" as="person" iteration="counter"><f:if condition="{counter.index} > 0">, </f:if>{person.name}</f:for>
+:Authors:
+   <f:for each="{extension.persons}" as="person" iteration="counter"><f:if condition="{counter.index} > 0">, </f:if>{person.name}</f:for>
 
 :Email:
-    <f:for each="{extension.persons}" as="person" iteration="counter"><f:if condition="{counter.index} > 0">, </f:if>{person.email}</f:for>
+   <f:for each="{extension.persons}" as="person" iteration="counter"><f:if condition="{counter.index} > 0">, </f:if>{person.email}</f:for>
 
 :License:
-   This extension documentation is published under the `CC BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__ (Creative Commons) license
-
-
+   This extension documentation is published under the
+   `CC BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__ (Creative Commons)
+   license
 
 {extension.description}
 
-
-
 **TYPO3**
 
-   The content of this document is related to TYPO3 CMS,
-   a GNU/GPL CMS/Framework available from `typo3.org
-   <https://typo3.org/>`_ .
+The content of this document is related to TYPO3 CMS,
+a GNU/GPL CMS/Framework available from `typo3.org <https://typo3.org/>`_ .
+
+**Community Documentation**
 
-**Community Documentation:**
+This documentation is community documentation for the TYPO3 extension {extension.name}
 
-    This documentation is community documentation for the TYPO3 extension {extension.name}
+It is maintained as part of this third party extension.
 
-    It is maintained as part of this third party extension.
+If you find an error or something is missing, please:
+`Report a Problem <https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/issues/new>`__
 
-    If you find an error or something is missing, please:
-    `Report a Problem <https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/issues/new>`__
+**Extension Manual**
 
-**Sitemap:**
+This documentation is for the TYPO3 extension {extension.extensionKey}.
 
-   :ref:`sitemap`
+**For Contributors**
 
-.. ---------------------------------------------------------------
-   This generates the menu
-   https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/MenuHierarchy.html
-   ---------------------------------------------------------------
+You are welcome to help improve this guide.
+Just click on "Edit me on GitHub" on the top right to submit your change request.
 
 .. toctree::
    :maxdepth: 3
-   :hidden:
 
    Introduction/Index
-   User/Index
+   Editor/Index
    Installation/Index
    Configuration/Index
    Developer/Index
    KnownProblems/Index
-   ToDoList/Index
    ChangeLog/Index
    Sitemap

Resources/Private/CodeTemplates/Extbase/Documentation.tmpl/Installation/Index.rst

@@ -1,17 +1,13 @@
-.. include:: ../Includes.txt
-
-
+.. include:: ../Includes.txt
 
 .. _installation:
 
 ============
 Installation
 ============
 
-Target group: **Administrators**
-
 - How is the extension installed?
 - Are there any dependencies that need to be resolved?
 
-You can also refer to general TYPO3 documentation, for example the
-:ref:`t3install:start`.
+References to general TYPO3 documentation are possible,
+for example the :ref:`t3install:start`.