Merge pull request #102 from mediumroast/alpha_2

Alpha 2 -doc

README.md

@@ -1,41 +1,47 @@
 ## Welcome to Open Source Mediumroast for GitHub.
 Products organizations must build robust product plans from competitive and customer interactions everyone can see, use, and reference. Therefore, Mediumroast for GitHub intends to help Products oranizations construct an active interactions repository close to the action of development and issue management in GitHub.
 
-**Notice:** We recommend that you read the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather the repository version. 
+**Notice:** We recommend that you review the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather than the repository version. 
 
 ## Installation and configuration
 Mediumroast for GitHub includes a [GitHub Application](https://github.com/apps/mediumroast-for-github), a Command Line Interface, and a Software Development Kit.  The following steps show you how to install the App and the CLI with SDK.
 
-### Preinstallation Requirements
+### Preinstallation requirements
 1. A GitHub organization, please 
 2. Permissions in your GitHub organization to install a GitHub application.
 3. Access to a command line terminal on Linux or MacOS.
 4. [Node.js installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-installer-to-install-nodejs-and-npm), ideally globally for all users.
 5. [NPM installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-installer-to-install-nodejs-and-npm), ideally globally for all users.
 
-### Step 1 - Install the Mediumroast for GitHub Application
+### Step 1 - Install the GitHub App
+Browse to the Mediumroast for GitHub [GitHub Application](https://github.com/apps/mediumroast-for-github) and: 
 
-### Step 2 - Install mediumroast_js via NPM
+1. Click install,
+2. Choose the location for the installation, usually your organization,
+3. Confirm the requested permissions, and
+4. Browse to your organization's `Settings > Third-Party Access > GitHub Apps` and confirm that Mediumroast for GitHub is installed.
+
+### Step 2 - Install mediumroast_js
 This package [mediumroast_js](https://www.npmjs.com/package/mediumroast_js) can be installed and removed via `npm`, several ways to install follow.
 
-#### Installation for Linux, UNIX and MacOS
+#### For Linux and MacOS
 Assuming the preinstallation requirements, installation of *node.js* and *npm*, are met please one one of the following.
 1. Global installation for all users: `sudo npm i -g mediumroast_js`
 2. Local installation for a developer or single user: `npm i mediumroast_js`
 
-#### Installation for WinOS
+#### For WinOS
 Coming soon.
 
-### Step 3 - Setup the Mediumroast for GitHUB CLI
-Before you can use the Mediumroast for GitHub CLI the environment must be setup.  With the CLI installed please run `mrcli setup` to start the setup process, note there's a video of the setup process in [CLI README.
+### Step 3 - Setup the CLI
+Before you can use the Mediumroast for GitHub CLI the environment must be setup.  With the CLI installed please run `mrcli setup` to start the setup process, note there's a video of the setup process in CLI README.
 
 ## What's provided
 Running `mrcli setup` creates a repository in your oganization called `<organization_name>_discovery` for all interactions and objects, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below.
 
 ### Warning
-Since the repository is a GitHub repository under the covers you can interact with it as a normal repository, but **doing so is not recommended**. If you interact with the repository in regular ways this could result in Mediumroast for GitHub becoming unoperable.  There are cases where it may become necessary to directly work with the repository, but that should be rare.
+Since Mediumroast for GitHub creates a regular repository you can interact with it as normal, but **doing so is not recommended**. If you interact with the repository, in regular ways, this could result in Mediumroast for GitHub becoming inoperable.  There are cases where it may become necessary to directly work with the repository, but that should be rare.
 
-### Example screenshot of in repositor companiesrReport
+### Example screenshot of in repository companies report
 <img width="1001" alt="companies" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/23fbd53f-dbfe-4106-a18d-5d13e0b5ce2b">
 
 ## Issues

cli/Company.md

@@ -1,89 +1,103 @@
-[Back](./README.md)
----
-# Companies
-Company objects are central to Mediumroast for GitHub. [Interactions](./Interaction.md) and in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with.  Additional companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities.  Each of the major functions for `mrcli company` are described in this document.
+## Companies
+Company objects are central to Mediumroast for GitHub. Interaction sand in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with.  Additional Companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities.  Each of the major functions for `mrcli company` are described in this document.
 
-## Notice
+### Notice
 Some of the command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit.
 
-# Help
+## Help
 Prints the usage for the `company` sub-command and exits.
-## Command(s) run
+
+### Command(s) run
 - `mrcli company --help`
-## Screenshot with output
-<img width="1266" alt="companies_help" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/6cd07f6f-02ad-4cac-8221-cb7af3307e26">
 
-# List company objects
+### Screenshot with output
+<img width="1178" alt="companies_help" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/6cd07f6f-02ad-4cac-8221-cb7af3307e26">
+
+## List company objects
 Print out one or more Companies to the command line or an alternative output mechanism like a CSV file.  Filtering can be applied to find Companies with specific attributes.
 
-## List all company objects in a table format
+### List all company objects in a table format
 This is the default output when running `mrcli c` or `mrcli company` which prints a text table to STDOUT.
-### Command(s) run
+
+#### Command(s) run
 - `mrcli c`
 - `mrcli company`
-### Screenshot with output
-<img width="1266" alt="companies_table" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/af9d22d8-4161-4ae9-9c57-06b65769a54e">
 
-## List all company objects in JSON format
+#### Screenshot with output
+<img width="1178" alt="companies_table" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/af9d22d8-4161-4ae9-9c57-06b65769a54e">
+
+### List all company objects in JSON format
 Output a list of company objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command.
-### Command(s) run
+
+#### Command(s) run
 - `mrcli c --output=json`
 - `mrcli company --output=json`
-### Screenshot with output
+
+#### Screenshot with output
 <img width="1178" alt="companies_json" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/22d46cd2-952f-4c3b-8e74-37bdceefee2a">
 
-## List all company objects and output to a CSV or XLSX
+### List all company objects and output to a CSV or XLSX
 Company data can be output in either a CSV or XLSX files to enable consumption in common tools like Microsoft Excel. The resulting files will be stored in $HOME/Documents directory as `Mr_Companies.csv` or `Mr_Companies.xlsx` depending on your intended output.
-### Command(s) run
+
+#### Command(s) run
 - `mrcli c --output=csv`
 - `mrcli c --output=xls`
-### Screenshot of commands being run
-<img width="1530" alt="companies_csv" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/f135de7a-aba8-4ed0-9198-64ff50797d4c">
+
+#### Screenshot of commands being run
+<img width="1178" alt="companies_csv" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/f135de7a-aba8-4ed0-9198-64ff50797d4c">
+
 ### Screenshot of CSV imported into MacOS numbers
-<img width="1627" alt="companies_numbers" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/6ab2266b-bacc-4cb0-9608-db8025866ccb">
+<img width="1178" alt="companies_numbers" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/6ab2266b-bacc-4cb0-9608-db8025866ccb">
 
-## Filter company outputs
-The CLI offers the ability to filter outputs by almost any company attribute.  This is manifest by two switches on the company sub-command one specific to finding companies by name, `--find_by_name` and the other by an arbitrary attribute, `--find_by_x`. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a company using any attribute you have to fully provide the attribute's value (i.e., "Med" wouod not matche Mediumroast, Inc., but "Mediumroast, Inc. would).
-### Filter in a company by name
+### Filter company outputs
+The CLI offers the ability to filter outputs by almost any company attribute.  This is manifest by two switches on the company sub-command one specific to finding companies by name, `--find_by_name` and the other by an arbitrary attribute, `--find_by_x`. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a company using any attribute you have to fully provide the attribute's value (i.e., "Med" would not match "Mediumroast, Inc.", but "Mediumroast, Inc." would).
+
+#### Filter in a company by name
 To zero in on a specific company using the find by name switch is provided.
-### Command(s) run
+
+#### Command(s) run
 - `mrcli c --find_by_name="Mediumroast, Inc."`
-### Screenshot with output
-<img width="1530" alt="companies_filter_by_name" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/4d6d88eb-740f-4d4d-a16b-bea12be54330">
-### Filter a company by attribute
+
+#### Screenshot with output
+<img width="1178" alt="companies_filter_by_name" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/4d6d88eb-740f-4d4d-a16b-bea12be54330">
+
+#### Filter a company by attribute
 Find a specific company by a particular attribute in the example below the switch filters on the attribute `company_type`.
-### Command(s) run
+
+#### Command(s) run
 - `mrcli c --find_by_x='{"company_type": "Public"}'`
-### Screenshot with output
-<img width="1786" alt="companies_filter_by_x" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/5c3e00d2-5365-40e8-bd91-31025cb821ae">
+
+#### Screenshot with output
+<img width="1178" alt="companies_filter_by_x" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/5c3e00d2-5365-40e8-bd91-31025cb821ae">
+
 # Update a company attribute
-To update a company attribute the `--update` switch is provided.  A properly formatted JSON stanza is supplied to the `--update` switch that specifies the name o the company to update, the key to update, and finally the value of the key to update.
+To update a company attribute the `--update` switch is provided.  A properly formatted JSON stanza is supplied to the `--update` switch that specifies the name of the company to update, the key to update, and finally the value of the key to update.
 
-## Command(s) run
+### Command(s) run
 - `mrcli c --update='{"name": "Atlassian Corp", "key": "company_type", "value": "Public"}'`
 
-## Screencast with output
+### Screencast with output
 
 https://github.com/mediumroast/mediumroast_js/assets/10818650/a74cb8cd-f8cb-4a8d-8968-ccf9b875d86b
 
-# Delete a company
+## Delete a company
 Remove a company and associated interactions if in the repository. There is a confirmation prompt which defaults to yes. Note that the exact company name is needed to proceed with a deletion.
 
-## Command(s) run
-- `mrcli c --delete="Atlassian Corp"
+### Command(s) run
+- `mrcli c --delete="Atlassian Corp"`
 
-## Screenshot with output
-<img width="1786" alt="companies_delete" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/85d98dee-ce3b-4d90-9567-9410e58872a3">
+### Screenshot with output
+<img width="1178" alt="companies_delete" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/85d98dee-ce3b-4d90-9567-9410e58872a3">
 
-# Add a company
+## Add a company
 A command line prompt based wizard steps the user through either a semi-automated process or a fully-automated process to define a company.  The semi-automated process is typically used for companies that aren't public.  While the fully-automated process is typically used for companies that are public.  In either case the user is asked to verify the steps taken before the company is committed to the repository.
 
-## Command(s) run
+### Command(s) run
 - `mrcli c --add_wizard`
 
-## Screenshot with output
+### Screenshot with output
 
-<img width="1786" alt="companies_add" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/d948fce2-6c31-4537-983d-9dad4c04c248">
+<img width="1178" alt="companies_add" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/d948fce2-6c31-4537-983d-9dad4c04c248">