More beginner friendly documentation

[raspher]

Looks like a lot of steps was missed in main documentation. I am currently searching google for my questions how to use this Elixir application (it's hard, cos Elixir is not as popular as JS/Python).

Beginners usually create bots or bot-like applications, but do not have knowledge about many things, they (and i) are learning them. How to learn this language without a good introduction?

For me, documentation like https://blog.kiprosh.com/developing-a-slack-bot-in-elixir-phoenix/ would be a nice practise. Not as verbose, but detailed and step by step.

I'm not blaming, just sharing my experience to create a better world 😄

---

Well, after fighting for ~5 hours, this didn't work for me, even it seems to be active project :/

[acconrad]

@raspher do you have ideas for specific areas you want more documentation? Just making a blanket statement that we need more documentation doesn't help us concretely solve this. How do you want this solved?

[raspher]

It would be awesome if we'd have guideline like hedwig-im/hedwig-slack have. I think all informations should be in separated files, /guides/ :

• how it works - project structure and files hierarchy
• slack - required permissions and token
• getting started - simple /hello world/ example with a little philosophy
• advanced features

A minimal project structure overview with description (files), a link to pattern design we use.

Slack:

• what permissions are required for bot to work (the essentials)
• • what permissions are required for addinational features (if possible a list)
• where are required tokens
• configuration - best practises (.env file, windows.env and (u?nix|linux|bsd).env)

Single node and single Slack workspace:

• how to connect to server (that bot would have green dot - is online)
• joining channel
• simple ping - pong, or Hi - Hello @user example
• pattern matching - how it's working, a link to regular expressions in Elixir
• what if bot should respong only when mentioned @bot ?

One step ahead:

• spawning bot process, so if it crashes, next bot process will start
• multiple bot processes, listening on different channels

I think that if someone want to use this bot on multiple workspaces or in distributed mode should be experienced enough to think how to do that.

There is hedwig-slack, which documentation is very user-friendly, but it's outdated and seems to be not enough maintained. Please threat "beginners" or "newcomers" as someone with near no experience in erlang/elixir, but have basic knowledge of programming. My list of things to be documented is a little verbose, but please understand that not only senior developers want to try this near perfect language, whose point of view, assumptions and whole language is way different compared to OO languages (C/C#/Python/Java...). I am not trying to make this project a tutorial how to write bot for XYZ in Elixir.

Please review my proposal and create a todo list if possible.

[acconrad]

@raspher this sounds good - but is a pretty serious investment. Are you open to creating some of these docs yourself?

[raspher]

Well it would be nice just start with as little information as possible but step by step. I can help a little but I'm out of time - studying, working, 2nd work...

I am 100% sure I can help with slack, can create beautiful introduction but I need information about needed permissions per feature available in hex docs

[amattn]

While more documentation is always helpful, I'd love to see a simple HelloWorld style example slack bot app.

Or pointers to open source slackbots that use Elixir-Slack.

Thank you