Improving Documentation (#220)

Documentation improvement (Related to https://github.com/JohnXLivingston/peertube-plugin-livechat/issues/117)

* new introduction and homepage
* Fix livechat_label shortcode: no line breaks
* refactoring/rewriting user documentation
* troubleshooting section
* Updating documentation po files
* ...

support/documentation/content/en/_index.md

@@ -5,8 +5,21 @@ You can use the language selector in the left menu to view this documentation in
 Some translations are missing or incomplete. In this case, you'll see the English version of the text.
 {{% /notice %}}
 
+![Chat screenshot](/peertube-plugin-livechat/images/chat.png?classes=shadow,border&height=200px)
+
+Welcome the **Peertube Livechat Plugin** documentation.
+
+[Peertube](https://joinpeertube.org/) is a decentralized streaming platform, that can provide both live streaming and VOD (Video On Demand) features.
+The present plugin adds chatting capatibilities to your Peertube installation, allowing viewers to interract with streamers.
+
+To have a glimpse on this plugin capabilities, checkout the [introduction](/peertube-plugin-livechat/intro/). For more precise informations, please find bellow the summary of this documentation.
+
+{{% notice tip %}}
+You can use the searchbox in the left menu to quickly find specific documentation parts.
+{{% /notice %}}
+
 {{% notice info %}}
 Before updating to a major release, please read the release notes and breaking changes list : [CHANGELOG](https://github.com/JohnXLivingston/peertube-plugin-livechat/blob/main/CHANGELOG.md).
 {{% /notice %}}
 
-{{% children style="li" depth="3" description="true" %}}
+{{% children style="li" depth="4" description="true" %}}

support/documentation/content/en/contributing/document/_index.md

@@ -89,6 +89,12 @@ To facilitate translators work, avoid making too long paragraphs.
 
 For now, it is not possible to use Markdown tables: the translation tools will break them.
 
+{{% notice warning %}}
+There may be links to documentation elsewhere on the web.
+Try not to change the urls of the documentation pages.
+Or at the very least, put links to the new location on the previous url.
+{{% /notice %}}
+
 ### What if I can't use hugo and/or po4a?
 
 Just edit english markdown files, and specify that you can't build translations when you make your Pull Request.

support/documentation/content/en/documentation/installation/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Installation guide"
 description: "Plugin peertube-plugin-livechat installation guide"
-weight: 10
+weight: 20
 chapter: false
 ---
 

support/documentation/content/en/documentation/installation/cpu_compatibility.md

@@ -1,7 +1,7 @@
 ---
 title: "Known issues: CPU Compatibility"
 description: "For now, the plugin only works out of the box for x86_64 and arm64 CPU architecture. Here are some instructions for other CPU architectures."
-weight: 10
+weight: 20
 chapter: false
 ---
 

support/documentation/content/en/documentation/installation/troubleshooting.md

@@ -0,0 +1,41 @@
+---
+title: "Troubleshooting"
+description: "Some classic mistakes and workarounds."
+weight: 10
+chapter: false
+---
+
+## I just installed/upgraded the plugin, but nothing happens
+
+If you have just installed/upgraded the plugin, but nothing happens (no chat, no settings, buttons in the settings page does not work, ...), just try to reload the page.
+
+## Diagnostic tool
+
+If the chat does not work, there is a diagnostic tool in the plugin's settings pages.
+
+Open the plugin settings, and click on the "launch diagnostic" button.
+
+![Launch diagnostic](/peertube-plugin-livechat/images/launch_diagnostic.png?classes=shadow,border&height=200px)
+
+If there is any error in the diagnostic page, you can search in this page for a solution, or refer to the [Bug tracking documentation page](/peertube-plugin-livechat/issues/) if you can't find any response.
+
+![Diagnostic result](/peertube-plugin-livechat/images/diagnostic.png?classes=shadow,border&height=200px)
+
+## Chat does not load
+
+### Internal API calls
+
+In some case (like for some Docker Peertube installation), the diagnostic tools displays an error for the test called "API Prosody -> Peertube is KO".
+
+In such case, try changing the "{{% livechat_label prosody_peertube_uri_label %}}" settings, by setting `http://127.0.0.1:9000` (assuming 9000 is the port on which Peertube listen, ask your instance administrators if you don't know).
+
+### Websocket
+
+If everything is fine in the diagnostic tools, but chat windows remains empty: it can be a Websocket issue.
+Since Peertube version 5.0.0, there are some additional configuration to do on the server side.
+Check with the instance administrators that they did not forgot to apply changes listes in the [Peertube v5.0.0 release notes](https://github.com/Chocobozzz/PeerTube/blob/master/CHANGELOG.md#v500).
+
+You can confirm that it is a Websocket issue by opening your browser console, and checking for error logs talking about failed Websocket connection.
+
+If you can't fix this immediatly, you can disable Websocket by unchecking "{{% livechat_label disable_websocket_label %}}" in the plugin setting page.
+In such case, you should also check "{{% livechat_label federation_dont_publish_remotely_label %}}", as chat federation won't work without Websocket.

support/documentation/content/en/documentation/user/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "User documentation"
 description: "Plugin peertube-plugin-livechat user documentation"
-weight: 40
+weight: 10
 chapter: false
 ---
 

support/documentation/content/en/documentation/user/moderation.md

@@ -1,21 +1,45 @@
 ---
 title: "Moderation"
 description: "Plugin peertube-plugin-livechat moderation"
-weight: 10
+weight: 30
 chapter: false
 ---
 
+{{% notice warning %}}
+This section is still incomplete.
+{{% /notice %}}
+
+## Accessing moderation tools
+
 You can access room settings and moderation tools by opening the chat in a new window,
 and using the dropdown menu at the top right.
 
-You can list all existing chatrooms: in the plugin settings screen, there is a button «List rooms».
-
-You can delete old rooms: join the room, and use the menu on the top to destroy the room.
-
-## Notes
+![Top menu](/peertube-plugin-livechat/images/top_menu.png?classes=shadow,border&height=200px)
 
+{{% notice tip %}}
 All instance moderators and admins will be owner of created chat rooms.
-If the video is local (not from a remote Peertube), the video owner will be admin in the chat room.
+The video owner will be admin in the chat room.
+{{% /notice %}}
 
 You can use [ConverseJS moderation commands](https://conversejs.org/docs/html/features.html#moderating-chatrooms) to moderate the room.
 When you open the chat room in full screen, there will also be a menu with dedicated commands on the top right.
+
+## Roles and affiliations
+
+There are several roles that can be assignated to users in chat rooms: owner, moderators, member, ...
+
+{{% notice warning %}}
+This section is still incomplete.
+{{% /notice %}}
+
+You can promote users as moderators, if you need some help.
+
+## Delete room content
+
+You can delete old rooms: join the room, and use the menu on the top to destroy the room.
+
+## Instance moderation
+
+As Peertube instance moderator or administrator, you will probably need to check that your users are not behaving badly.
+
+You can list all existing chatrooms: in the plugin settings screen, there is a button «List rooms».

support/documentation/content/en/documentation/user/obs.md

@@ -1,21 +1,31 @@
 ---
 title: "OBS"
 description: "Documentation to stream the chat content using OBS."
-weight: 10
+weight: 40
 chapter: false
 ---
 
+[OBS](https://obsproject.com) is a popular Free And Open Source streaming software, with advanced capacities for your live streams.
+In the current page, you will find some adviced to handle your live chats using OBS.
+
 ## OBS Overlay
 
-If you are using OBS for streaming, you can easily include the chat in your stream.
+You can easily include the chat in your stream.
 
-You can use the «share chat link» feature to generate an URL to your chat.
-The button should be near the chat if you are the video owner (unless it was desactivated by your server admins).
+![Embeding the chat in a live stream](/peertube-plugin-livechat/images/embed_chat_in_livestream.png?classes=shadow,border&height=200px)
 
-Check the «readonly» checkbox in the modal.
-Then use this link as a «web browser source» in OBS.
+You can use the "{{% livechat_label share_chat_link %}}" feature to generate an URL to your chat.
+This button should be near the chat if you are the video owner (unless it was desactivated by your server admins).
 
-You can use the «Transparent background» to have a transparent background in OBS.
+Check the "{{% livechat_label read_only %}}" checkbox in the modal.
+
+![Share link popup](/peertube-plugin-livechat/images/share_readonly.png?classes=shadow,border&height=200px)
+
+Then use this link as a "web browser source" in OBS.
+
+![Embeding the chat in OBS](/peertube-plugin-livechat/images/embed_chat_in_obs.png?classes=shadow,border&height=200px)
+
+You can use the "{{% livechat_label transparent_background %}}" option to have a transparent background in OBS.
 If you want to customize the background transparency, you can add this CSS in your OBS browser source's settings:
 
 ```css
@@ -24,7 +34,9 @@ If you want to customize the background transparency, you can add this CSS in yo
 }
 ```
 
-Note: you can customize colors. This is undocumented yet, but you can try this:
+In the previous CSS snippet, you can of course change the color or the transparency, by adapting the color values.
+
+Note: you can entirely customize chat colors. This is undocumented yet, but you can try this:
 in the modal, check «use curent theme colors», then you can try to manually change color values in the URL.
 You must use valid CSS color values, and they must be properly URL encoded.
 

support/documentation/content/en/documentation/user/streamers.md

@@ -0,0 +1,89 @@
+---
+title: "For streamers"
+description: "How to setup the chat for your live stream"
+weight: 20
+chapter: false
+---
+
+## Enabling the chat for you live streams
+
+{{% notice warning %}}
+Instance administrators can choose to disable or enable chat in specific cases.
+Information in this section are only true in the default case.
+{{% /notice %}}
+
+When you create or modify a Peertube live, there is a "plugin settings" tab:
+
+![New live](/peertube-plugin-livechat/images/new_live.png?classes=shadow,border&height=200px)
+
+In the "plugin settings" tab, there is a "{{% livechat_label use_chat %}}" checkbox.
+Just check or uncheck it to enable or disable the chat associated to your video.
+
+![Activate the chat](/peertube-plugin-livechat/images/new_live_activate_chat.png?classes=shadow,border&height=200px)
+
+{{% notice tip %}}
+There can be other settings in this tab, depending on plugins installed on your Peertube instance.
+{{% /notice %}}
+
+### Per channel chat
+
+On the instance level, Peertube's adminstrators can choose if chat rooms are unique per video, or if there will be an unique chat room per channel.
+Please contact your instance's administrators for more information on how they configure the livechat plugin.
+
+## Share the chat
+
+On top of the chat, there is a "{{% livechat_label share_chat_link %}}" button.
+
+This button opens a popup, where you can obtain an url to join the chat.
+This url can be shared.
+
+![Share link popup](/peertube-plugin-livechat/images/share_readonly.png?classes=shadow,border&height=200px)
+
+You can customize some options:
+
+* {{% livechat_label read_only %}}: you will only be able to read the chat, not write. This is useful to include the chat content in your live stream (see the [OBS documentation](/peertube-plugin-livechat/documentation/user/obs)).
+* {{% livechat_label use_current_theme_color %}}: if checked, your current theme colors will be added to the url, so that any user that opens the link will have the same color set.
+* {{% livechat_label generate_iframe %}}: instead of an url, you will obtain an HTML snippet that you can add to your website to embed the chat.
+
+The "{{% livechat_label share_chat_link %}}" popup can also contain a "{{% livechat_label connect_using_xmpp %}}" tab.
+This will only be available if your instance's administators have enabled an correctly configured this option.
+Using this option, you can provide a link to join the chat using any [XMPP client software](https://en.wikipedia.org/wiki/XMPP#Clients).
+Using such softwares can for example facilitate moderation actions.
+
+## Moderation
+
+Please refer to the [moderation documentation](/peertube-plugin-livechat/documentation/user/moderation).
+
+## Include the chat in your video stream
+
+Please refer to the [OBS documentation](/peertube-plugin-livechat/documentation/user/obs).
+
+## Chat persistence
+
+By default, the chat is persistent.
+This means that the room content will be kept for a while.
+User joining will see messages posted before their arrival.
+
+You can change the persistence behaviour.
+[Open the chat in fullscreen](/peertube-plugin-livechat/documentation/user/viewers), then open the top menu and click on "Configure".
+
+![Top menu](/peertube-plugin-livechat/images/top_menu.png?classes=shadow,border&height=200px)
+
+There are several option that can be changed.
+
+![Configure chat room](/peertube-plugin-livechat/images/top_menu.png?classes=shadow,border&height=200px)
+
+You can for example set the default and maximum number of messages to return to 0, so that new incomers won't see any previously sent message.
+
+You can also uncheck "enable archiving": if unchecked, the message will be pruned in the server restarts.
+
+By unchecking "Persistent", the room will be cleared if there is no more participant.
+
+## Delete the chat content
+
+If you want to delete the chat content, [Open the chat in fullscreen](/peertube-plugin-livechat/documentation/user/viewers), then open the top menu and click on "Destroy".
+A popup will open, asking a confirmation.
+To avoid errors, the popup will ask you the "XMPP address" of the chat room.
+This address can be obtain using the "Details" menu in the top menu.
+
+The chat will be automatically recreated each time someone tries to join it as long as the video exists, and has the "{{% livechat_label use_chat %}}" feature activated.

support/documentation/content/en/documentation/user/viewers.md

@@ -0,0 +1,81 @@
+---
+title: "For viewers"
+description: "How to chat for stream viewers"
+weight: 10
+chapter: false
+---
+
+## Joining chat rooms
+
+When you are watching a Peertube video that has the chat activated, you will see the chat next to the video:
+
+![Chat screenshot](/peertube-plugin-livechat/images/chat.png?classes=shadow,border&height=200px)
+
+There are two slightly different use cases, depending on wether or not you have an account on the Peertube instance.
+See bellow for more informations.
+
+### If you haven't a Peertube account
+
+{{% notice warning %}}
+This feature can be disabled by the instance's adminitrators.
+{{% /notice %}}
+
+If you are not logged in on the Peertube instance where you are watching the video, you will automatically join the chat.
+You will be assigned a random nickname (something like "Anonymous 12345").
+
+![Chat with an anonymous user](/peertube-plugin-livechat/images/chat_with_anonymous.png?classes=shadow,border&height=200px)
+
+Before being able to speak in the chat room, you have to enter a nickname in the field on the bottom of the window.
+
+![Joining chat when not connected](/peertube-plugin-livechat/images/chat_anonymous.png?classes=shadow,border&height=200px)
+
+### If you have a Peertube account
+
+If you are connected with your Peertube account, you will automatically join the room, using your Peertube nickname and avatar.
+
+{{% notice tip %}}
+If you are watching a live on an instance on which you have no account, but you have an account on another instance:
+if the plugin is installed on both instances, it is possible to join the chat using your account.
+To do so, just open the video on your instance (you can for example copy/paste the video url in the search field of your instance).
+{{% /notice %}}
+
+## Chatting
+
+To send messages, just type them in the "message" field on the bottom of the screen.
+You can send them by pressing the enter key on your keyboard, or by clicking on the "send" button.
+
+If you want to add line breaks in your messages, you can use the "shift+enter" key combinaison.
+
+You can add emojis to your messages.
+You can for example use the emojis menu, or directly type emojis shortcuts like `:smiley:`.
+
+You can mention other participants.
+To do so, you can type the first nickname letters, then press the tab key.
+You can also type `@`: this will directly open the menu.
+You can also click on a nickname in the participants list to insert it in the message field.
+
+## Participants list
+
+To see the list of participants, just open the right menu:
+
+![Participants list](/peertube-plugin-livechat/images/open_participants_list.png?classes=shadow,border&height=200px)
+
+You can see that some participants have special rights (moderator, owner, ...).
+
+## Opening full screen
+
+On top of the chat, there is a button to open the chat in fullscreen.
+This will open a new browser tab with the following content:
+
+![Fullscreen chat screenshot](/peertube-plugin-livechat/images/fullscreen.png?classes=shadow,border&height=200px)
+
+It can be easier to chat using a full browser tab.
+
+This fullscreen view also adds a top menu with advances features.
+This is especially useful for [moderation features](/peertube-plugin-livechat/documentation/user/moderation).
+
+## Changing nickname
+
+You can change your nickname by typing `/nickname your_new_nickname` in the message field.
+
+You can also change your nickname using the top menu when you are in fullscreen mode.

support/documentation/content/en/documentation/user/xmpp_clients.md

@@ -1,7 +1,7 @@
 ---
 title: "XMPP Clients"
 description: "Connect to chat using a XMPP client"
-weight: 40
+weight: 60
 chapter: false
 ---
 

support/documentation/content/en/intro/_index.md

@@ -5,17 +5,80 @@ weight: 5
 chapter: false
 ---
 
-This [Peertube](https://joinpeertube.org/) plugin is meant to provide chat system for Peertube videos.
+## What is the livechat plugin?
 
-{{% notice tip %}}
-You can use the language selector in the left menu to view this documentation in different languages.
-Some translations are missing or incomplete. In this case, you'll see the English version of the text.
-{{% /notice %}}
+This [Peertube](https://joinpeertube.org/) plugin is meant to provide a chat system for Peertube videos.
+
+By default, once you have installed the plugin on your Peertube instance, a chat room will automatically be created for each live stream.
+
+On the following screenshot, you can see a classic Peertube video page, with a chat room on the right (click on the picture to view it full screen):
 
 ![Chat screenshot](/peertube-plugin-livechat/images/chat.png?classes=shadow,border&height=200px)
 
+The chat room will be accessible for all viewers, even those who don't have an account on your instance. Those "anonymous" users just have to choose a nickname before they can begin talking in the chat.
+
+By default, the chat is displayed next to the video.
+But you can open it in another browser tab, using the button on top of it :
+
 ![Fullscreen chat screenshot](/peertube-plugin-livechat/images/fullscreen.png?classes=shadow,border&height=200px)
 
 {{% notice tip %}}
-See a [demo](https://www.yiny.org/w/399a8d13-d4cf-4ef2-b843-98530a8ccbae).
+You can test the livechat plugin with this [demo page](https://www.yiny.org/w/399a8d13-d4cf-4ef2-b843-98530a8ccbae).
 {{% /notice %}}
+
+## Installation
+
+As a Peertube administrator, you can setup this plugin on your instance simply by using the Peertube plugin marketplace included in the administration interface.
+Search for "livechat", then click "install": that's it!
+
+![Livechat installation](/peertube-plugin-livechat/images/installation.png?classes=shadow,border&height=200px)
+
+## Livechat capabilities
+
+The plugin has many advanced features.
+As it is using the [XMPP](https://xmpp.org/) standard "under the hood", it is possible for Peertube administrators to allow advanced usages (connection using XMPP clients, chatbots, bridge to other chat protocols, ...).
+More information in the relevant sections of this documentation.
+
+## Federation
+
+Peertube is part of the fediverse: you can create a network of Peertube instances, sharing content between them.
+
+This plugin can handle federation: when viewing a livestream from a remote instance, you will join the chat room with your local account.
+You will be automatically connected with your current nickname and avatar.
+
+Of course, for the federation to work, the plugin must be installed on both instances.
+
+## Moderation
+
+Some times, you have to protect your community from bad people.
+As an instance administrator, you can choose to disallow federation for the livechat plugin.
+If remote actors behave badly, streamers, moderators and administrators can ban or mute users.
+
+## Chat persistence
+
+When joining a room, you will see previous messages.
+Even those sent before you joined the room.
+
+This behaviour can be changed room by room, and default retention duration can be chosen by instance's administrators.
+
+## Integrate the chat in your live stream
+
+When using software as [OBS](https://obsproject.com) for you live stream, you can embed the chat in the video stream.
+This is for example useful for replays.
+
+In the following screenshot, you can see a live replay, where the chat content is embeded on bottom of the video:
+
+![Embeding the chat in a live stream](/peertube-plugin-livechat/images/embed_chat_in_livestream.png?classes=shadow,border&height=200px)
+
+In the following screenshot, you can see an OBS setup, where the chat is included as a source in the current scene (background color can be changed, and can be transparent):
+
+![Embeding the chat in OBS](/peertube-plugin-livechat/images/embed_chat_in_obs.png?classes=shadow,border&height=200px)
+
+## Other usages
+
+By default, each streamer will be able to activate/deactivate the chat for their live streams.
+
+But on the instance level, administrators can choose to activate the chat for all videos (live and/or VOD).
+
+You can even activate the chat for specific VOD videos.
+This is how the [demo](https://www.yiny.org/w/399a8d13-d4cf-4ef2-b843-98530a8ccbae) page works: it is not a live stream, but I have activated the chat specifically for this video.