Pages and topics (#166)

Co-authored-by: Carolina Romero <[email protected]>
Co-authored-by: paulinebessoles <[email protected]>

.github/styles/config/vocabularies/Decidim/accept.txt

@@ -2,6 +2,7 @@ Config
 CSV
 [Dd]ecidim
 [Ee]mail
+[Ff]aq
 [Mm]oderations
 [Nn]ickame
 [Oo]fficialization

docs/en/modules/ROOT/nav.adoc

@@ -39,7 +39,9 @@
 *** xref:admin:scopes.adoc[Scopes]
 *** xref:admin:areas.adoc[Areas]
 *** xref:admin:help_sections.adoc[Help sections]
-** xref:admin:pages.adoc[Pages]
+** xref:admin:pages.adoc[Pages and Topics]
+*** xref:admin:pages/pages.adoc[Pages]
+*** xref:admin:pages/topics.adoc[Topics]
 ** xref:admin:participants.adoc[Participants]
 *** xref:admin:participants/admins.adoc[Admins]
 *** xref:admin:participants/groups.adoc[Groups]

docs/en/modules/admin/pages/pages.adoc

@@ -1,125 +1,35 @@
-= Pages
+= Pages and topics
 
-You can configure static Pages, which contains general information to the participants of the platform.
+== Understand the basics
 
-As an example, some of these pages could refer to:
+The pages tab allow you to publish static pages including, for example, your platform's Terms and Conditions, accessibility statements, FAQs, etc.
+You can organize these pages in different topics, acting as kind of folders. 
 
-* What's this platform? Who's the organization?
-* How can I participate here?
-* How can I create and verify my account?
-* What are the terms of conditions and the legal information about this platform?
+NOTE: Looking for how to create topics and pages? See xref:pages/pages.adoc[Pages] and xref:pages/topics.adoc[Topics].
 
-These pages will be available to all the participants through the **Help** top menu section and also at the footer sections. You can define **Topics** to categorize all of these pages.
+These pages are available to all the participants through the **Help** section in the header and in the footer.
 
-As the platform enables the Participants to sign up (register) and save some of their personal data, it's important that there's an especial page, called **Terms and Conditions**. This is where you need to put your legal terms, for instance which entity has control of this data, how much time does this data will be saved, etc. This should be (ideally) written and (at least) reviewed by a lawyer.
+== Configuration
 
-== Create a new page
+To access the Pages configuration panel, go in the administration panel and click the "Pages" item in the administration navigation bar. 
 
-For creating a new page, you need to:
+image::pages/pages_menu.png[Pages: Access pages panel]
 
-. Sign in as admin
-. Click in Pages in the sidebar menu
-. Click in "Create page"
+There, you are able to create, update, or delete xref:admin:pages/pages.adoc[Pages] and xref:admin:pages/topics.adoc[Topics]. 
+You can start by creating only pages if you want, as you are able to create topics and reorganize pages inside them at any moment. 
 
-image::pages_backend_form.png[Backend: new page form]
-
-.New page form
-|===
-|Field |Type |Description
-
-|Title
-|Required
-|Title of this page. For instance: "How to participate?"
-
-|URL Slug
-|Required
-|String that will be used on the URL. Use partial paths, not full URLs here. Accepts letters, numbers, dashes and slashes, and must start with a letter. For instance if the slug is "hello-world" and your domain is "https://example.org", your page will be at "https://example.org/hello-world"
-
-|Content
-|Required
-|All the text of the page.
-
-|Topic
-|Optional
-|In which Topic it'll be in.
-
-|Weight
-|Optional
-|Which order will it have in relation with the other pages. Having a lower number means a higher priority. For instance, if you have two pages, "Page a" with weight "10" and "Page b" with weight "0", then "Page b" will be first when ordering.
-
-|Show in the footer
-|Optional
-|Wether you want to show this page in the general footer (available in every page).
-
-|===
-
-image::pages_frontend_footer.png[Frontend: example of a page in the footer]
-
-== Create a new topic
-
-For creating a new topic, you need to:
-
-. Sign in as admin
-. Click in Pages in the sidebar menu
-. Click in "Create topic"
-
-image::pages_backend_topic_form.png[Backend: new topic form]
-
-.New topic form
-|===
-|Field |Type |Description
-
-|Title
-|Required
-|Title of this topic. For instance: "Help"
-
-|Description
-|Optional
-|What's this topic is about.
-
-|Weight
-|Optional
-|Which order will it have in relation with the other topics. Having a lower number means a higher priority. For instance, if you have two topics, "Topic a" with weight "10" and "Topic b" with weight "0", then "Topic b" will be first when ordering.
-
-|Show in the footer
-|Optional
-|Wether you want to show this topic in the general footer (available in every page).
-
-|===
-
-== Special "Terms and Conditions" page
-
-This is where you need to put your legal terms, for instance which entity has control of this data, how much time does this data will be saved, etc. This should be (ideally) written and (at least) reviewed by a lawyer.
-
-It's generated by default in a new installation. It can't be deleted, and it has a few special details related with its legal nature:
-
-. It's shown in the text area sign up form
-. If there are meaningful changes, it has a field that can allow an admin  when it's necessary that the participants accept the "Terms and Conditions" again, in the next sign in.
-
-image::pages_backend_tos_change.png[Backend: ToS change]
-
-image::pages_frontend_tos_change.png[Frontend: ToS change]
-
-If a participant rejects to accept the terms, then they have three options:
-
-. To review this again later. It signs them out automatically.
-. To download their personal data
-. To delete their account
-
-image::pages_frontend_tos_reject.png[Frontend: ToS reject]
+image::pages/pages_backend_list.png[Backend: list pages]
 
 == Examples
 
-=== Pages
-
-image::pages_frontend_show.png[Frontend: show a page]
+=== A page without topic
 
-image::pages_backend_edit.png[Backend: edit a page]
+image::pages/pages_frontend_show.png[Frontend: show a page]
 
-image::pages_backend_list.png[Backend: list pages]
+=== A page with a topic
 
-=== Topics
+image::pages/pages_frontend_show_topic.png[Frontend: show a page with topic]
 
-image::pages_frontend_list_topics.png[Frontend: list topics of pages]
+=== Help section with pages and topics
 
-image::pages_backend_list_topics.png[Backend: list topics of pages]
+image::pages/pages_frontend_list_topics.png[Frontend: list topics of pages]

docs/en/modules/admin/pages/pages/pages.adoc

@@ -0,0 +1,82 @@
+= Pages
+
+In this section, you can configure static Pages, to give general information to the participants of the platform.
+
+As an example, some of these pages could refer to:
+
+* What's this platform? Who's the organization?
+* How to participate here?
+* How to create and verify an account?
+* What are the terms and conditions and the legal information about this platform?
+
+== Manage the pages
+
+You can manage the pages from this section of the administration panel: 
+
+image::pages/pages_backend_list.png[Backend: list pages]
+
+As you can see, you can edit all the pages and re-organize them in different topics at any moment. 
+
+There is only one page you can't delete. As the platform enables the Participants to register and save some of their personal data, it's important to have a page for the **Terms and Conditions**. 
+This is where you need to put your legal terms, for instance who owns the data collected, for how many times it's saved, etc. This should ideally be written and reviewed by a lawyer.
+
+== Create a new page
+
+To create a new page, you need to click the "Create page" button. 
+
+image::pages/pages_backend_form.png[Backend: new page form]
+
+.New page form
+|===
+|Field |Type |Description
+
+|Title
+|Required
+|Title of this page. For instance: "How to participate?"
+
+|URL Slug
+|Required
+|String used in the URL. Use partial paths, not full URLs here. Accepts letters, numbers, dashes and slashes, and must start with a letter. 
+For instance if the slug is "faq" and your domain is "https://example.org" your page is accessible at "https://example.org/pages/faq"
+
+|Content
+|Required
+|All the content of the page.
+
+|Topic
+|Optional
+|In which Topic it's stored.
+
+|Order position
+|Optional
+|The order of the page in relation with the other pages. Having a lower number means a higher priority. 
+For instance, if you have two pages, "Page a" with weight "10" and "Page b" with weight "0" then "Page b" is first when ordering.
+
+|===
+
+== Edit a page
+
+You can edit the pages at any moment, by clicking on the pencil icon in the pages list. 
+All the content and configuration of the page are editable. 
+
+image::pages/pages_backend_edit.png[Backend: edit a page]
+
+== The "terms and conditions" page
+
+This page is generated by default in every new organization. It can't be deleted, and it has a few specific details related with its legal nature:
+
+. It is shown to participants when they sign up, and they have to accept it to be able to participate ;
+. If there are meaningful changes, administrators can decide that all users have to accept the new version at their next sign in ;
+. The structure of this page can be more complex than the other ones, with summary and two-columns sections. 
+
+image::pages/pages_backend_tos_change.png[Backend: ToS change]
+
+image::pages/pages_frontend_tos_change.png[Frontend: ToS change]
+
+If a participant refuses to accept the terms, then they have three options:
+
+. To review it again later. It signs them out automatically.
+. To download their personal data.
+. To delete their account.
+
+image::pages/pages_frontend_tos_reject.png[Frontend: ToS refusal]

docs/en/modules/admin/pages/pages/topics.adoc

@@ -0,0 +1,42 @@
+= Topics
+
+In this section, you can configure Topics, to organize your static pages and provide more clarity to the participants. 
+
+== Manage the topics
+
+To access the topics list, click the Topics tab at the top of the panel. 
+Here, you are able to edit, delete, and create topics for your static pages. 
+
+image::pages/pages_backend_list_topics.png[Backend: list topics of pages]
+
+== Create a new topic
+
+To create a new topic, click the "Create topic" button.
+
+image::pages/pages_backend_topic_form.png[Backend: new topic form]
+
+.New topic form
+
+|===
+|Field |Type |Description
+
+|Title
+|Required
+|Title of this topic. For instance: "Help"
+
+|Description
+|Optional
+|What's this topic is about.
+
+|Order position
+|Optional
+|The order of the topic in relation with the other topics. Having a lower number means a higher priority. 
+For instance, if you have two topics, "Topic a" with weight "10" and "Topic b" with weight "0" then "Topic b" is first when ordering.
+
+|Show in the footer
+|Optional
+|Wether you want to show this topic in the "Help" section of the general footer (accessible in every page).
+
+|===
+
+image::pages/pages_frontend_footer.png[Frontend: example of a page in the footer]