Move documents into /docs folder

[andrew]

An attempt to move towards making the package-managers repo a real repository of documentation that's easier to index, read and contribute to.

Starting by copying content from some of the more chunky issues into markdown files and moving some existing markdown docs into a docs folder.

I'm proposing this approach rather than enabling and using the wiki as GitHub's wiki functionality doesn't really allow any kind of discussion as it's not really integrated into pull requests or issues at all.

Started by wholesale copy-pasta some issues, the plan is to transform each document into something more akin to a chapter of a book that expands and improves as we go.

Closes #16
Closes #17
Closes #22
Closes #41
Closes #50
Closes #52
Closes #56

[jessicaschilling]

@andrew Thanks for doing this! I was also looking sadly at the wiki "functionality" this morning and was also thinking about building out labels for issues for sorting/discoverability purposes -- something combining these two approaches:
https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63 for good naming practices
https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues/ for use of color

Actually, I should probably open a separate issue to discuss this ... see #54 .

[andrew]

@jessicaschilling proper labeling would be 👌, I personally prefer simple word labels rather than but don't really mind how they end up. One thing that would be good to include with a new label system would be a labeling document in the repo so people know how to label their issues correctly.

We added one to our CONTRIBUTING.md on Octobox: https://github.com/octobox/octobox/blob/master/docs/CONTRIBUTING.md#our-labels

[andrew]

@jessicaschilling I wonder if there's a way to get wafflebot to ignore this repository, or at least stop using the old in progress label

[andrew]

Looks like Waffle is shutting down on May 16, 2019, so that problem may solve itself in a week.

[jessicaschilling]

Haha, I was just typing exactly that.
Also, glad the thread is in chronological order again 😄
I'll set myself a reminder to kill off the old in progress label after the 16th!

[andrew]

@jessicaschilling I was thinking of closing the issues that this PR effectively copies into /docs, so the issues list becomes more like a task list, think that makes sense?

[jessicaschilling]

@andrew Yes, exactly. I was envisioning that discussions would start out as issues labeled Type: Discussion topic and move into /docs if they expanded enough to turn into topics of significance. Sound good?

[andrew]

👍 Updated this PR to automatically close those issues when it's merged.

[momack2]

Suggestion: if there’s an obvious order in which to read these docs, start their titles with 1_, 2_ to put them in the right order. If not, then I think we should flesh out the index to help people decide which doc to dive into when/for what purpose.

[jessicaschilling]

Per @momack2 suggestion - I think a well-annotated index file is the more futureproof solution (keeps us from having to change file titles later). @andrew, I’m happy to write that up in a separate PR once you merge this one if you don’t want to deal with it.

[andrew]

I'll add an index file to this PR, there's not an obvious order to the docs at the moment.

[andrew]

Added an index, going to merge now.