Description
openedon Aug 1, 2023
Requested Feature
I'd like, for Sopel 8, to move part of the website's documentation into the project's documentation. The goal of this issue is to discuss which sections/parts we want exactly. I'd like to have a curated list of frequent issues and errors our users encountered in the past, things that we always have to answer to.
For instance, I'd like to improve the running the bot chapter with the following sections and information:
- how to install the bot (to replace /usage/installing)
- Sopel's list of feature (including a description of the per-channel feature)
- how to manage plugins, where are they installed, how to install more, etc.
- an FAQ with things like "my command doesn't run" and advice on how to troubleshoot some of the most common problems
I also think we could rework a bit our contribution guide, for example to add the appendix about the core plugin.
Maybe even... have a Design Document that outline the core tenet of Sopel's software architecture? Well... maybe not right now, but that would be lovely to consider!
As for the website, I think we could use it more to promote Sopel's feature, promote "official" plugins, share some links... I believe it still has a place and could be useful. It could also be used to host a sopel-help generated html page. That's something for another issue tho.
Problems Solved
Today, there are two locations for our documentation, and that's one too many in my opinion. So moving everything (or at least the most relevant things) into one place would solve that issue. It would streamline the workflow of upgrading the doc at the same time as the code.
Alternatives
Keep the website and upgrade it as we go, which we don't really do as it's separate from the code and all, and we have to keep the doc for the current version released, it means having open PR and stuff. So maybe we should change our workflow a bit to make it easier. But that's only the alternative here!
Notes
I was supposed to make a PR for 2497 but I think it's better to talk about that before really diving into that. I'd love some feedback and ideas to write this part of the documentation.