search

hikari-py / hikari

A Discord API wrapper for Python and asyncio built on good intentions.
https://docs.hikari-py.dev/en/stable
MIT License
815 stars 94 forks source link

Add a guides section to the docs for newcomers to the library #1064

Closed hypergonial closed 2 years ago

hypergonial commented 2 years ago

Summary

Ideally this should be located in a prominent section of the documentation, and touch on common topics on how to get a bot running. If given the go-ahead, I (and many others) would contribute to this and add guides on specific topics.

Why is this needed?

It can be argued that guides do not belong in documentation, or that they should be located in-line along with the auto-generated documentation, but I still feel that some form of centralized step-by-step instructions for newcomers would help ease the burden of figuring out hikari, as currently I feel that the weakest point of hikari is approachability.

Ideal implementation

Something along the lines of what lightbulb does currently with it's documentation, but there are many more examples of this: https://hikari-lightbulb.readthedocs.io/en/latest/guide.html

Checklist

FasterSpeeding commented 2 years ago

This feels similar to #835

hypergonial commented 2 years ago

I would argue it is different to a getting started section, as instead of providing a general starting point to the library, this aims to target specific topics (E.g. commands, components, embeds), while a getting started section is more analogous to lightbulb's getting started page.

FasterSpeeding commented 2 years ago

I would argue it is different to a getting started section, as instead of providing a general starting point to the library, this aims to target specific topics (E.g. commands, components, embeds), while a getting started section is more analogous to lightbulb's getting started page:

ngl i don't really see the difference there. those are all topics that would be covered by a getting started segment for Hikari and lightbulb's "getting started" page isn't what I would've had in mind for a getting started segment for Hikari at all since you couldn't ever fit decent explanations of the most import functionalities exposed by Hikari in such a small page and hikari already has an equivalent to that lightbulb page in the README

hypergonial commented 2 years ago

Alright, closing it then! :)

FasterSpeeding commented 2 years ago

We're going to do add a getting started section to the docs eventually, just nobody's gotten around to it yet and it can't be worked on until the current open docs pr is done anyways.

hypergonial commented 2 years ago

We're going to do add a getting started section to the docs eventually, just nobody's gotten around to it yet and it can't be worked on until the current open docs pr is done anyways.

Understood, thanks!