[ WIP ] Add documentation (publiclab#258)

* add docs overview page.

* add getting started.

* update readme file.

* fixed the video guide link

README.md

@@ -1,82 +1,77 @@
-Community Toolbox
-====
+## Community Toolbox
 
-A toolbox of a GitHub organization's contributor community.
+A platform dedicated to community growth and getting insights on organization-wide activities.
 
-See a live instance (set up for Public Lab's community) at: http://code.publiclab.org/
+[![Code of Conduct](https://img.shields.io/badge/code-of%20conduct-green.svg)](https://publiclab.org/conduct)
+[![first-timers-only-friendly](http://img.shields.io/badge/first--timers--only-friendly-lightgray.svg?style=flat-square)](https://code.publiclab.org#r=all)
+[![Join the chat at https://publiclab.org/chat](https://img.shields.io/badge/chat-in%20different%20ways-blue.svg)](https://publiclab.org/chat)
+[![visit here](https://img.shields.io/badge/live_at-URL-yellow)](https://code.publiclab.org/)
+[![GitHub license](https://img.shields.io/github/license/publiclab/community-toolbox)](https://github.com/publiclab/community-toolbox/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/publiclab/community-toolbox)](https://github.com/publiclab/community-toolbox/stargazers)
+[![Newcomers welcome](https://img.shields.io/badge/newcomers-welcome-pink.svg)](https://img.shields.io/badge/newcomers-welcome-pink.svg)
 
 
-## Embed an issues list
+## Table of Contents
 
-Community Toolbox lets you view issues of a specific repository for embedding on another site, with the following URL:
+1. [Project Overview](#project-overview)
+2. [Getting Started](./docs/getting_started.md)
+2. [How to Use](./docs/usage.md)
 
-http://code.publiclab.org/examples/embed.html#o=orgname&r=repository
 
-For issues with a specific label, use, for example: 
+## Project Overview
 
-http://code.publiclab.org/examples/embed.html#o=orgname&r=repository&l=first-timers-only
+The project structure of community toolbox is majorly divided into two groups,
+- `/examples` contains code responsible for front-end styles and related scripts,
+- `/src` contains the actual code for fetching data and showing it to the user.
 
-To embed these on your site, use an `<iframe>` like this:
+![](./images/overview.png)
 
-```html
-<iframe src="http://code.publiclab.org/examples/embed.html#o=orgname&r=repository" style="border:none;" width="100%" height="600px"></iframe>
-```
+As shown in the flowchart, `/src` inherits MVC like architecture. Here,
 
-## Org-wide issues
+Fragment | Contains
+--- | ---
+`/models` | database related operations (Database layer)
+`/scripts` | main source file (community-toolbox.js)
+`/utils` | utility functions (Controller layer)
+`/UI` | user interface functions (View layer)
 
-You can also use Community Toolbox to display issues for a given label across an entire organization. Use `all` for the `r` parameter, like this:
+---
 
-http://code.publiclab.org/#r=all
+### models
 
-## Repository specific issues
-To find an issue in a specific repository, other than using the issues tab and the search bar, you can change the URL to filter through the issues! So if we look at the URL for embed.html:
-https://publiclab.github.io/community-toolbox/examples/embed.html
+`models/` corresponds to the **Database Layer**. It is responsible for all the operations that happen on the database i.e., create, read and delete operations. The structure of `models/` ensures the segregation of code chunks based on their responsibilities.
 
-To get to the issues of a specific repository, you can add a #r= then the name of the repository you want to looks through. For example, if you wanted to look through the issues in the plots2 repo, you would add #r=plots2 to the above URL. 
+There are 3 major categories to this:
+- Setting up/initializing the database (initialize.js),
+- Defining operations for the database (crud.js), and
+- Providing a layer to communicate with the outside code (utils.js)
 
-The default is #r=all. This will looks though all repositories and show only the first-timer-only issues in all the repositories. 
-You can combine the above to search through specific issues in a specific repository. For example, you can add #r=all&l=help-wanted. The l= is where the name of the label on the issues you are looking for goes. Here's what that looks like in a full URL:
-https://publiclab.github.io/community-toolbox/examples/embed.html#r=all&l=help-wanted
+![](./images/models.png)
 
-## Configuration
 
-[These lines](https://github.com/publiclab/community-toolbox/blob/620c4d906be704ffaa5b40509796c18c393f83f4/index.html#L115-L118) allow configuration of the example to set **repository, organization** and **labels** to use, by adding to the URL hash in the format: `https://publiclab.github.io/community-toolbox/#r=all` (for the `r` parameter, as an example). So the options are:
+### scripts
 
-* **repository** - using `r=` you can set the repository name to look at, like: http://code.publiclab.org#r=plots2 for https://github.com/publiclab/plots2
-* **organization/user** - using `o=` you can set the organization or user name to look at, like: http://code.publiclab.org#o=publiclab for https://github.com/publiclab
-* **first-timers-only label** - using `f=` you can set the label to use for `first-timers-only` or equivalent issues, like: http://code.publiclab.org#f=help-wanted for https://github.com/publiclab/plots2/labels/help-wanted
-* **first timers only "candidates"** - using `c=` you can set the label to use for `fto-candidate` or equivalent issues (at Public Lab, we keep a queue of not-quite-ready-but-almost issues for newcomers, that have key information but aren't completely formatted to welcome yet), like: http://code.publiclab.org#c=fto-candidate for https://github.com/publiclab/plots2/labels/fto-candidate
+`scripts/` contains the main entry point **_community-toolbox.js_** which is responsible for plugging every single functionality to the website. This file provides an interface to communicate with every feature that is present or is to be added later on. This file then gets bundled up with the help of grunt and that bundled-up version of the file is injected into the website as a script with the help of the landing page html file (index.html).
 
-## Developing
 
-To develop and build out Community Toolbox, you'l need to have `npm` installed and to run `npm install` to get all the dependencies. 
+### utils
 
-Community Toolbox is built using a Grunt task from the source files in `/src/`, and the compiled file is saved to `/dist/community-toolbox.js`. To build, run `grunt build`. To watch files for changes, and build whenever they occur, run `grunt`. 
+`utils/` acts as a **Controller Layer**, it contains code for various different features, majority of the code for any feature is present in this folder. This is to follow our approach of keeping main logic separate from the interface file (community-toolbox.js). This helps in making the code more readable and maintainable.
 
-API calls are based on: https://www.npmjs.com/package/github-api-simple
 
-## Install Instructions
-* Clone or download the repo. into any fresh temporary folder.
+![](./images/utilscripts.png)
 
-   ``` git clone https://github.com/publiclab/community-toolbox.git ```
+### UI
 
-* Cd into that root folder you just cloned locally.
+`UI/` acts as a **View Layer**, it is responsible for displaying data on the landing page. Data is given to UI functions and its their job to display that data on to the screen. These functions are broken up into different units according to the data they display.
 
-   ``` cd community-toolbox ```
+- Data for repository contributors is displayed on the screen with the help of **_contributorsUI.js_**,
+- Similarly, **_recentContributorsUI.js_** shows recent contributors' data on to the page, and likewise other functions show data accordingly.
 
-* Open terminal in the current folder and to install all dependencies type
 
-   ```npm install ```
-
-   Update to new version of packages if required in package.json.
-
-* Now go to the folder and open index.html in browser.
+![](./images/UI.png)
 
 
-## Testing
+### Up next
 
-To run tests, execute 
-
-```
-npm test
-```
+ - ### [Getting started guide](./docs/getting_started.md)

docs/getting_started.md

@@ -0,0 +1,61 @@
+Getting Started
+====
+
+So you're almost there, just some info before you start building amazing things with us,
+
+- To develop and build out Community Toolbox, you'll need to have `npm` installed. Run `npm install` to get all the dependencies installed.
+
+- Community Toolbox is built using a Grunt task from the source files in `/src/`, and the compiled file is saved to `/dist/community-toolbox.js`. To build, run `grunt build`. To watch files for changes, and build whenever they occur, run `grunt`. 
+
+- Most of the API calls are based on [github-api-simple](https://www.npmjs.com/package/github-api-simple) library.
+
+## Developing :rocket: :tada:
+
+### Installation instructions [ [Watch video guide](https://youtu.be/wkC2AgLiaTM) ]
+
+* Clone or download the repository into any fresh temporary folder.
+
+   ``` git clone https://github.com/publiclab/community-toolbox.git ```
+
+* Cd into that root folder you just cloned locally.
+
+   ``` cd community-toolbox ```
+
+* Open terminal in the current folder and to install all dependencies run
+
+   ```npm install ```
+
+   Update to new version of packages if required in package.json.
+
+* Now go to the folder and open `index.html` in browser.
+
+* You are all set now, you can start making changes and see them taking place at `index.html` in the browser (you need to be doing `grunt build` for any changes you make in the `src/` folder).
+
+
+### Testing
+
+So after you've done changes, run 
+```
+npm test
+```
+to execute test suites.
+
+
+## Contributing :computer:
+
+We are happy to see you here and we welcome your contributions towards community-toolbox. Contributions are not limited to coding only, you can help in many other ways which includes leaving constructive feedback to people's Pull Request threads also.
+
+Community-toolbox also provides an extensive list of issues, some of them includes labels like `first-timer-only`, `fto-candidate` and `help-wanted`. You can take a look at `first-timer-only` issues if you are new here but you are free to choose any issue you would like to work on.
+
+If there's no issue available currently, you can take a look at the list of `stale issues` on [code.publiclab.org](https://code.publiclab.org) which contains issues that do not have their status updated for about 2 weeks.
+
+After choosing an issue and doing changes in the code regarding that, you can open up a Pull Request (PR) to get your work reviewed and merged!
+
+Here's a short GIF that helps in getting familiar with the process of opening a new Pull Request,
+
+![](../images/howtoopenpr.gif)
+
+
+### Up next
+
+ - ### [Usage](./usage.md)

docs/usage.md

@@ -0,0 +1,57 @@
+How to use
+====
+
+Take a look below for some of the ways you can use Community Toolbox,
+
+## Embed an issues list
+
+Community Toolbox lets you view issues of a specific repository for embedding on another site, with the following URL:
+
+```
+http://code.publiclab.org/examples/embed.html#o=orgname&r=repository
+```
+
+For issues with a specific label, use, for example: 
+
+```
+http://code.publiclab.org/examples/embed.html#o=orgname&r=repository&l=first-timers-only
+```
+
+To embed these on your site, use an `<iframe>` like this:
+
+```html
+<iframe src="http://code.publiclab.org/examples/embed.html#o=orgname&r=repository" style="border:none;" width="100%" height="600px"></iframe>
+```
+
+## Org-wide issues
+
+You can also use Community Toolbox to display issues for a given label across an entire organization. Use `all` for the `r` parameter to get the view of all repositories' data, like this:
+
+```
+http://code.publiclab.org/#r=all
+```
+
+## Repository specific issues
+To find an issue in a specific repository, other than using the issues tab and the search bar, you can change the URL to filter through the issues! So if we look at the URL for embed.html:
+
+```
+https://publiclab.github.io/community-toolbox/examples/embed.html
+```
+
+To get to the issues of a specific repository, you can add a #r= then the name of the repository you want to look through. For example, if you wanted to look through the issues in the plots2 repo, you would add #r=plots2 to the above URL. 
+
+The default is #r=all. This will look though all repositories and show only the first-timer-only issues in all the repositories. 
+You can combine the above to search through specific issues in a specific repository. For example, you can add #r=all&l=help-wanted. The l= is where the name of the label on the issues you are looking for goes. Here's what that looks like in a full URL:
+
+```
+https://publiclab.github.io/community-toolbox/examples/embed.html#r=all&l=help-wanted
+```
+
+## Configuration
+
+[These lines](https://github.com/publiclab/community-toolbox/blob/620c4d906be704ffaa5b40509796c18c393f83f4/index.html#L115-L118) allow configuration of the example to set **repository, organization** and **labels** to use, by adding to the URL hash in the format: `https://publiclab.github.io/community-toolbox/#r=all` (for the `r` parameter, as an example). So the options are:
+
+- **repository:** Using `r=` you can set the repository name to look at, like: http://code.publiclab.org#r=plots2 for https://github.com/publiclab/plots2
+- **organization/user:** Using `o=` you can set the organization or user name to look at, like: http://code.publiclab.org#o=publiclab for https://github.com/publiclab
+- **first-timers-only label:** Using `f=` you can set the label to use for `first-timers-only` or equivalent issues, like: http://code.publiclab.org#f=help-wanted for https://github.com/publiclab/plots2/labels/help-wanted
+- **first timers only "candidates":** Using `c=` you can set the label to use for `fto-candidate` or equivalent issues (at Public Lab, we keep a queue of not-quite-ready-but-almost issues for newcomers, that have key information but aren't completely formatted to welcome yet), like: http://code.publiclab.org#c=fto-candidate for https://github.com/publiclab/plots2/labels/fto-candidate