cc: reword and rewrite as needed for improved brevity & clarity

[jo3-l]

Similar to #23, but for the custom command category. These are largely very minor, albeit uncontroversial, nits and there are some diffs that are just my editor reflowing text (though I've tried to keep that to a minimum) -- sorry for the noise!

That said, I do have some more substantive feedback pertaining to these pages as a whole which are perhaps more interesting. In particular, I am wondering whether their current length is warranted; I worry that excessively long documentation may turn off users and hinder skimming. Compare, for instance, the custom command interface page with its equivalent on the learn.yagpdb.xyz Gitbook. The latter is considerably more succinct for two main reasons:

1. Better spacing and formatting choices. For instance, the Gitbook uses an ordered list for the trigger types, whereas the new documentation here uses different subheadings, which leads to (in my opinion) inefficient space usage; see screenshot.

   Click to expand

   

2. Less detail (when appropriate) — 'leaving the obvious unsaid'. Though the idea that less detail produces shorter documentation seems self-evident and entirely meaningless, I think it actually constitutes a meaningful difference in approach between the new and old documentation that we should address. In particular, the new documentation describes, at length, what amounts to every single button and configuration knob available, even those whose function are seemingly obvious. An example:

   The commands page lists the commands (2) in the selected group (6). They are ordered by [ID] and display their name (if set), [trigger type], and trigger text (if applicable). You can expand the command by clicking on it, which displays the full command response.

   The above text, while not incorrect, simply describes what a user sees on accessing the control panel -- and so, personally, I do not believe it is necessary to reiterate in the documentation. I would much rather focus on the more subtle details, common use-cases and pitfalls, and so on, and leave the obvious unsaid save perhaps for a brief bullet-point overview. WDYT?

Terms

• I have read and understood this project's Contributing Guidelines

[jo3-l]

@SoggySaussages, I addressed your review comments in the latest commit -- thanks for those. What are your thoughts on the meta feedback re: documentation approach? (It might be easier to discuss this via Discord, feel free to ping me there if more convenient.)

[l-zeuch]

Similar to #23, but for the custom command category. These are largely
very minor, albeit uncontroversial, nits and there are some diffs that
are just my editor reflowing text (though I've tried to keep that to a
minimum) -- sorry for the noise!

Thanks for this patchset. The noise is alright, it's bound to happen
when reworking text in any way whatsoever.

I went through your changes and they look good to me, so I'll merge this
quite soon(tm).

However, I do feel obliged to comment on a few things you mentioned
before doing so:

That said, I do have some more substantive feedback pertaining to
these pages as a whole which are perhaps more interesting. In
particular, I am wondering whether their current length is warranted I
worry that excessively long documentation may turn off users and
hinder skimming.

I agree with this sentiment. Personally, I am a fan of the Archlinux
Wiki and their very D.R.Y. approach — linking to pages that already
cover a topic X instead of repeating (that also includes summarising)
it. I tried to go with a similar approach in my patches, but may have
failed in some places.

The [GitBook] is considerably more succinct for two main reasons:

1. Better spacing and formatting choices. For instance, the
   Gitbook uses an ordered list for the trigger types, whereas the new
   documentation here uses different subheadings, which leads to (in my
   opinion) inefficient space usage; see screenshot.

While correct, my main gripe with a list (be that ordered or unordered)
is that it isn't easy to link to specific items, without bloating up the
Markdown file with considerable amounts of in-line HTML, thus defeating
the point of Markdown.¹

Though, I may be wrong, and there is a lean and clear way to link to
specific list items in such a way that one can easily copy the link
thereto.

2. Less detail (when appropriate) — 'leaving the obvious unsaid'.
   [...] In particular, the new documentation describes, at length, what
   amounts to every single button and configuration knob available even
   those whose function are seemingly obvious.

See my initial comment about the Archlinux Wiki. KISS may also be
applicable here, seeing as explaining every single button is definitely
not "keeping it simple".

The above text, while not incorrect, simply describes what a user sees
on accessing the control panel -- and so, personally, I do not believe
it is necessary to reiterate in the documentation. I would much rather
focus on the more subtle details, common use-cases and pitfalls, and
so on, and leave the obvious unsaid save perhaps for a brief
bullet-point overview. WDYT?

Certainly agreed. As for a way of going forward with this constant cycle
of write new page 1 -> reword -> write new page 2 -> ..., I think we
should employ a more stringent review on new submissions, and perhaps
thoroughly review the current pages to see if we can trim them down to
acceptable levels of KISS and DRY.

Currently, I generally wait for a week to have reviews dabble in, which
are mostly a few wording things. Seeing as this PR and #23 were
necessary, this current approach makes no sense, as we could have
saved us some work and done it correctly the first time.

---

[tangential]

Another thing I would like to note; I have received some feedback from
@User9684 regarding the screenshots. They are, as of now, quite busy.
This is mostly my fault, because I specifically said "label as much as
possible". In hindsight (which is always 20/20) this is obviously a
terrible idea, as one tends to quickly lose focus on what is important.

With that in mind, some future patches should rework these screenshots
to have less labels, instead focussing on the thing(s) that are
currently discussed. If we do go forward with this approach, I'll
research a way to automatically improve images for serving on the web,
i.e. compressing them.

Alternatively we could outright remove any and all images, minus the few
small ones, but that option seems rather nuclear to me. We are, after
all, documenting a graphical interface.

[/tangential]

---

Footnotes

1. Although, granted, users will mostly view the rendered HTML rather
   than the raw Markdown. Despite that, I'd personally prefer keeping the
   Markdown as clean as possible, to make it easier to read and edit. ↩

[jo3-l]

While correct, my main gripe with a list (be that ordered or unordered)
is that it isn't easy to link to specific items, without bloating up the
Markdown file with considerable amounts of in-line HTML, thus defeating
the point of Markdown.

Indeed. I wonder if the tradeoff of linking to a general section but using a list (so improved brevity and ease-of-skimming) is worth abandoning separate but tiny shortsections that take up much vertical space. Alternately, we could try to restyle the pages to reduce wasted whitespace, though I don't know how effective such an effort would be.

With that in mind, some future patches should rework these screenshots
to have less labels,

I think so as well and fully agree.

[l-zeuch]

Alternately, we could try to restyle the pages to reduce wasted
whitespace, though I don't know how effective such an effort would be.

I think this is an option worth exploring. I have some minor cosmetic
adjustments planned already, so I'll just lump that in with those,
whenever I get to doing it.