Link documentation to official errbot site

errbotio / err-backend-slackv3

Slack Events and RTM backend for Errbot

GNU General Public License v3.0

27 stars 28 forks source link

Link documentation to official errbot site #84

Closed nzlosh closed 1 year ago

nzlosh commented 2 years ago

To avoid duplicating maintenance effort between the readme and the official documentation, the README will now link to errbot's official documentation.

nzlosh commented 2 years ago

This PR is to be merged after https://github.com/errbotio/errbot/pull/1602 and the official documentation has been published.

sijis commented 2 years ago

I believe it should be the other way around. The main docs should point to here.

Installing and setup will likely change at a faster pace
The backend docs are more representative of what is actually going on
Easier to iterate on changes/documentation

nzlosh commented 2 years ago

I was in favour of using the errbot documentation for the following reasons:

central point for all errbot documentation.
branded (colour theme and logo) with table of contents and pages by category for easier navigation.
dedicated documentation site gives a more mature/professional image of the project than github readme.
provides cohesive experience without being sent off site.

That said, I agree with all the points you're making and wonder if it would be possible to move the documentation into its own repository so that it can be maintained by core and backend devs with it's own release cycle? Alternatively, perhaps creating a readthedocs page dedicated to the slackv3 backend may be a reasonable compromise?

sijis commented 2 years ago

Moving the documentation to its own repo seems appealing but the api documentation is built based on the codebase.

I think it does make sense to include a "quick setup" guide on the main site but add a link to the slackv3 repo that includes more details an examples in the README, like updating messages, replying in a thread, etc.

That should solve the ideas of keeping a similar branding and central document and includes the flexibility for the repo to add additional context/information about features of the backend.

nzlosh commented 1 year ago

@sijis I've added the quick start instructions as you suggested. This PR includes the sphinx configuration for readthedocs as well a few spelling corrections.