[Discussion]: Integrating Info For Self-Hosters Into Documentation

[l-zeuch]

This thread serves to discuss the way going forward on how to integrate infos about selfhosting into the documentation. A transcript of relevant parts of the discussion as started in https://github.com/botlabs-gg/yagpdb-docs-v2/pull/15#discussion_r1597730721 follows.

---

@jo3-l:

I think it should be made more clear that this section is really only relevant to those self-hosting YAGPDB.

@l-zeuch:

Personally I think it is better to move anything relevant to selfhosters into its own category, which will mostly be just configuration values by then. This way we can keep the main categories clean and focused on end-user features. WDYT?

@SoggySaussages:

I'm conflicted. I believe that the documentation should be for all users, including self hosters, hence why I've elected to include extra detail about inner workings of the bot in many places where the end-user wouldn't particularly care. On the other hand, I could see there being a section for end users and a section for hosters. I do think however that I personally prefer having the documentation of a feature thoroughly describe the feature's use and workings with detail and specificity.

When looking at similar bots such as Red, their documentation is primarily aimed at the hoster with detailed descriptions of how the end user would use the features later on. Contrastingly, MEE6 documentation is composed of a series of tutorials walking the end user through setting up each plugin step by step. YAG docs fall somewhere in the middle, but the current version leans more towards the MEE6 docs than the Red docs, which I personally don't love.

I think in an ideal world we have a full documentation and then quick start guides for end-users setting up plugins. Maybe expanding the learn page to all plugins of the bot rather than exclusively custom commands?

I think I could maybe see a subpage for self hosting on each relevant category, but I think putting self hosting anything in its own category, a), with subpages for each plugin would be messy and a waste of space, just mirroring the end user layout but under a self hosting category, or b), putting everything on a single page, requiring users to jump up and down a single page to get to information about several completely unrelated plugins just doesn' sit right with me. With either option we are forcing users to jump back and forth between the end user and self hoster's documentation for the same plugin.

---

Soggy summarised it quite well, there are very valid reasons for both approaches.

A reason for a separate chapter is that we (more or less) clearly signal "this is a separate thing", though the subliminal message behind that sectioning may be lost on the average user. It might also be lost on me, sometimes.

Another reasoning for this approach is that the entire configuration for a self-hosted YAGPDB instance can fit on one page. That way, everything you need to know for self-hosting is in one place, instead of being scattered through the entire document.

That said, however, and thinking intensely about this, I am more inclined to agree with Soggy. If we clearly mark information for self-hosters as such (as suggested by Joe), maybe even put them at the very end (as is already the case in #15), we should be in the clear.

That way, it is still decently clear that this is a separate thing, but we don't have to maintain yet another page. It should also be easier to document new features, because we only have to focus on one page, instead of remembering to add it to a separate self-hosting section.

Please let me know what you think, especially if you're reading this as an end-user. (hi!)

[jo3-l]

Copying some comments I made on Discord:

---

First, to go on a slight tangent from the topic of the issue at hand, I want to try to justify a position gently opposed to Soggy's re: detail of documentation.

I think in an ideal world we have a full documentation and then quick start guides for end-users setting up plugins.

While I agree that separation of tutorials and reference documentation would be nice, it is not realistic. People come and go -- Satty, for instance, started learn.yagpdb.xyz but has now been inactive for years (not to blame him at all, to be clear. Life gets all of us.)

With this in mind, I think we need to be more realistic with our goals as opposed to working toward an effectively unattainable ideal. By that, I mean we should try to write one -- and only one -- good set of documentation, targeted toward the most common audience, that is, typical users of the official instance of YAGPDB, who are not self-hosting and are utterly uninterested in the machinery behind how YAGPDB works under the hood if it is not absolutely relevant for understanding. In a similar vein...

I do think however that I personally prefer having the documentation of a feature thoroughly describe the feature's use and workings with detail and specificity.

My personal preference aligns with yours. But we should recognize that not enough people read the documentation as is, and part of the problem is long, complex digressions and detail that appear irrelevant to the end-user's problem at first glance.

In brief: I firmly believe that short tutorial-like articles are the way to go, à la MEE6, not Red.

---

Now back to the topic of the issue. I have no objection to keeping material for self-hosters and users of the official instance in the same document (as opposed to separating them), but feel that information specific to self-hosters should be hidden by default. We can extend the Hugo theme to add a global switch or toggle to easily show/hide the relevant sections. I think this suggestion is uncontroversial and will please everyone, so it is just a matter of implementation.

[l-zeuch]

In light of our new roadmap as discussed in #documentation on Discord I removed the blocking status of this issue.

Our first priority is to get the documentation done as a whole and then we will implement the advanced view for selfhosters, as well as a potential theme switch as suggested by Esen.