Create documentation for Teams App

[alicetragedy]

Even for pretty experienced developers, it's difficult to get started contributing to the Teams App without any information about context. The tests do provide some information, but I think it's not enough for people who have never used the Teams app before. My suggestion is to create documentation that will provide the following information for contributors and core organisers who sometimes just need to know how certain things work, but don't have knowledge of the code base:

• [ ] a breakdown of the different roles and quick overview of what they mean and do (example: a student should be able to do this and that)
• [ ] an explanation of the different phases (e.g. Project submission phase, Application phase, Selection phase...)
• [ ] Information about how mail delivery works in production (e.g. sendgrid)
• [ ] maybe style-guide preferences?
• [ ] other information that might be valuable for organisers who are not devs:
• do participating members in a conversation for project submissions get notified about new comments?
• different pages that can be accessed via /orga (since we don't have a dashboard yet)
• [ ] information about db backups? production env? yearly cloning of the repo? Rollbar? this can also be in a private repo, but it should be somewhere (and not just in someone's head) ;)

There is probably a lot of stuff I've missed, so feel free to post comments with more suggestions (or get a conversation going about items you don't agree with). I could imagine a 2017 team working on it as their feedback would be incredibly valuable, but we could/should also get started internally as soon as possible, as it might help us to get things shipped in the next weeks.

[bitboxer]

A explanation about the process on how people work with tickets would be super helpfull, too. What are those labels? Who is setting them, what do I have to do when I want to work on a ticket/finish a ticket?

[alicetragedy]

A lot of this information (labels, picking up a ticket) is found in the contribution guide. I'm not 100% sure about this, but I think external collaborators (e.g. people who have not been added to a team on GH) might not be able to set labels to issues themselves. And because of the way GH works, I think they also cannot assign themselves or be assigned to an issue unless they're added to the organisation/repo?

[bitboxer]

Yes, you can't set them but there is also waffle.io who is setting labels (i wasn't aware of that and got a bit confused :wink: )

And I am still not 100% clear what "in progress" means with pull requests. When I have a finished pull request, but it is still labeled as "in progress", what should i do? Is this okay? The contribution guide ends at the pull request.

[alicetragedy]

Yeah, I think “in progress” is added automatically by waffle.io. I don't use it, so I have no idea how to turn that off, but we should probably investigate this 🙈

[acnagy]

I'm new, but I'd really like to help document the teams app. Partly because documentation is awesome and important, and partly because there's no better way to get up to speed. :) What can I do to jump in?

[emcoding]

Hi @acnagy! Welcome aboard!!

A first step would be to follow the Quick Start Guide in the Readme. See if you can set up the app if you follow the steps, and if not: what and where was different. For example with setting up the database, with signing in, etc. Maybe take screenshots of each step. Also: what happens when you make a mistake. Can you trace your steps or are you getting lost? (I know I was, when I tried to set it up the first time. 😨 )

Next step could be to read the documentation that we have, and see if that makes sense to you. There is a kind of an introduction in the wiki. Does that makes sense? What do you miss for an overview?

And what do you think about a home page in the wiki? With an outline of the info it should cover. @alicetragedy 's list is a great start.

[alicetragedy]

@acnagy I think Maud's comment is a great way to get started and see if you encounter any issues there.

[beanieboi]

@acnagy thanks for taking care of this! <3

[acnagy]

@F3PiX Can do! I'm working on it... - will post notes + relevant screenshots 👍

[acnagy]

Hiya again @F3PiX! I decided to try setup twice, so I knew when to get screenshots... that first time through was unexpectedly confusion 😅 - I found myself jumping all over the README for information... that said, some general notes from Testing Round 1:

1. I'm not totally clear how much background info/ability to infer we assume new contributors have. For example, we give instructions on how to install postgres with homebrew and create a user as a sort of block of commands in System Requirements ... but we do not tell the contributor to start their server.
2. Related: the quick start guide generally doesn't give commands on how to start the application, i.e. ./bin/rails server or foreman run rails server... I'd assume that would be the place to find those - rather than before the quick start guide embedded in the discussions on additional services
3. We mention troubleshooting errors for additional services in the docs before the quickstart guide - if you read the docs through sequentially, it's tricky to know how to know if those troubleshooting steps will be relevant.

Anyway... now that I've fixed some issues specific to my environment (yay, permissions....), I'm going to start from scratch again and take screenshots and/or copy/paste console output for the docs. I'll do a PR to the README as well to restructure/edit text based on my experience.

[emcoding]

Interesting adventures :-) So, you are creating ONE doc that features all the steps in the right sequence, right? And maybe with links to the wiki for background info for special cases? I love that. About the details: I think in docs where we give detailed steps, we need to include where and how to start the server. Otherwise the detailed steps make no sense. Great that you are working on this!

[acnagy]

@F3PiX That's the plan - yes! Updates to the README for getting started/general setup, with additional (especially, troubleshooting) information on the wiki. I should have a PR with the README changes incoming soon :)

[acnagy]

I opened up a WIP PR over in https://github.com/rails-girls-summer-of-code/rgsoc-teams/pull/764 - still quite a few "interesting" behaviors to investigate/document, but that's the structure of the readme I've written so far :) I anticipate that some of this content will turn to wiki pages soon, but I'd like to get everything written before I go moving it around. Contributions to the refresh-docs branch are more than welcome 💛

[alicetragedy]

Awesome @acnagy! ✨ I've added myself as a reviewer, I should have time to look at it tomorrow or early next week — but of course I encourage anyone (@F3PiX ?) to make comments on and review the PR as well :)