Lack of New Contributor Documentation

[b4ux1t3]

I've been meaning to help out with HTBox for a while now, and I've finally been able to set aside some time to start getting 2WR stood up and kicking the tires to get a feel for the app before I start looking at open issues.

There is a bit of friction getting started. I've been able to get the application running in debug, but that's about it.

I hope this doesn't get taken as "you're doing everything wrong, you should fix this for me!", but I wanted to lay out some of the difficulties I've had getting started. If anyone can help me gather some of this info, I'd be happy to flesh out some of the READMEs myself and submit a few PRs.

Auth0 Integration

In the README and in the root of the Vue project, there is an example of a .env file. While sticking that info into a new .env file makes it so you can log in to the app, there's no good documentation of how the auth works. It might be obvious if you're familiar with Vue and/or Auth0 (of which I am overly-familiar with neither). However, some documentation on what callback URLs need to be added to Auth0 (for example) would be helpful!

A sub-issue here, for me, was my lack of experience with Auth0 specifically. I don't expect a detailed primer on Auth0 (they have an excellent one on their site), but I'd love to see a surface-level description of what the environment variables do and the basic flow from App -> Auth0 -> App.

Application Architecture

There's a lot going on here. Three different applications, essentially, each with their own tech stack and runtime requirements. I know there are some UML/class diagrams/ERDs in the Wiki, but I had trouble parsing through them. Each individual README gives a brief overview of how to get its parts of the app running, but there isn't a good description of how they all fit together. A "Getting Started" doc, in the Wiki or in the root README, would help get potential contributors going a lot faster.

Contributor Guidelines

Besides the (currently empty) style guide over on the wiki, there isn't a lot of guidance for new contributors, such as:

• Generally accepted contribution types (new features vs bug fixes vs documentation updates)
• Where to find/ask for more info on the app's development (a Slack/Discord/Discourse/forum/whatever). Even a list of Twitter handles would help.

---

That's what I have for now. Like I mentioned previously, I'd be happy to start submitting documentation PRs, once I've gotten my hands a bit more dirty.

[oneolddev]

@b4ux1t3

On familiarizing yourself with Auth0, I found these Get Started with Auth0 Video Series helpful.