Guide/Tutorials Improvements

[kyranet]

The docs are still far from perfect, and we would like feedback from our developers to help us improving them before Klasa 1.0.0 release.

Between the issues we could notice:

• Some parts are not correctly clarified, causing confusions to our new developers.
• The learning curve isn't fully normalized and starting with Klasa is way very hard for many new developers. For the easiness we give, and with the consistency we keep with discord.js, this should not be an issue, but in the current state, it is, perhaps we need to show this to our users.
• Lack of use-cases of Klasa, "Building Your Bot" guides, etc. This affects user retention, and we would like to help them with better examples.
• Lack of examples, we have many many lines of code, whilst they are fully documented, they do not provide good examples.

[Tylertron1998]

Yeah, I completely agree with all of this. Here are some things I've noticed -

• Lack of differing guides; e.g. the custom piece/store guide. This is a very narrow and odd use case, imo, and it is quite confusing for a newbie developer.

• Some documentation is missing.

• I think cross-referencing certain pieces of Klasa together would be really awesome; to show bits of Klasa working together; e.g. a Finalizer, SG, and Timestamp tutorial for command-runtime saving.

• A little more explanation on what goes on behind the scenes would be nice. Again, Klasa is powerful, and for someone who doesn't know what they are doing, it almost seems like magic.

• Explaining what a piece could be used for - e.g. "An inhibitor could be used for having certain command enabled at certain times, e.g. every Sunday, or for making sure commands are only used in a certain channel." This would help inspire Klasa-Users to use Klasa to its full potential.

• Some sort of a basic guide to show what you would need to do when moving from a d.js bot to a Klasa bot; nothing too in depth, but things like changing client.on('message', message => to a monitor, putting events in the event folder; etc.

• Possible links to where things have been used - e.g. in a guide about using SG, a link to the pieces repo where you can see it "in action" so to speak. This, however, I feel would need more pieces to be contributed to be used.

I have some more ideas which I'll put here later; but I think the main getaway is for newbie developers, they don't really see the indepth and powerful parts of Klasa, and normally ask in the Discord Guild "Is it possible to do X and Y with Klasa"; of which half the time, there is a built in method or piece for it.

[kyranet]

Informally assigned the contributors @Tylertron1998 and @KingDGrizzle as requested in our Discord Server. (Github does not allow to assign issues to contributors, only to +Collaborators).

[gc]

I made a plan for a tutorial on fully creating and deploying a bot from scratch to a cloud server, if anybody has any input or feedback on it or wants to help make it: https://gist.github.com/gc/a6528433d1e7650400bed0c6364e7620

[mason-rogers]

@gc The guide is meh, if some people are new to Linux systems they won't now how install node and such via CLI. You should go in depth with it and show the commands and such.

[gc]

What I posted is not a guide or tutorial, its a plan for one. I just listed the titles for each section, like a table of contents, and a very summarized description of what goes in each section. The tutorial made from this plan would definitely explain every step in great detail, so that somebody who doesn't know what Linux or Git is can still do it, with image/files alongside the text to help.

[cfanoulis]

bump.

I'd like to make a formal request to take this on.

[hbjydev]

We should get a TypeScript tutorial added to this too. Plus typings are out of date @kyranet

[kyranet]

Typings are not out of date, but I'll consider typescript tutorials/guides.

[hbjydev]

They were for CommandUsage. It takes 4 arguments. Until #616, typings file suggested it only took 2

[MrJacz]

That is one thing, that doesn't mean typings are broken it means that there was one thing that was missed while going thru typings. I don't think this is the place to argue about typing as it isn't related to them. plus this spams people's emails

[kyranet]

One thing I have just noticed, the current guides are basically a cookbook than a guide. They don't lead the developer, at the current state they guide in the very basic operation: creating a Klasa instance with its options.

The point of a guide is to lead the user from start to end, not only in the very start and then give unrelated stuff that does not continue, there's a connection missing between both parts and there is no continuity.

We also have to explain what certain concepts are, such as "pieces", as it's mentioned a lot in the guides and documentation, but in no place we explain this.

[hbjydev]

Can I get a bump on that TypeScript setup?

[cfanoulis]

Reviving this since we're real close to the library revolution v0.0.1 of @klasa/core:
Has anyone made any progress on this? I'll probably make an officially unofficial gitbook for klasa guides, and I want to see what other people have done.

[cfanoulis]

status update on the above: The gitbook is made https://klasa.fanoulis.dev. If anyone is feeling like contributing, the gitbook is open-source, on https://github.com/cfanoulis/the-klasa-cookbook. I'm looking into making this like An Idiot's Guide, but for Klasa