art-institute-of-chicago · nikhiltri · May 17, 2024 · May 10, 2024
diff --git a/README.md b/README.md
@@ -3,22 +3,22 @@
 # JourneyMaker CMS
 > A Twill CMS site to administer content
 
-[JourneyMaker](http://www.artic.edu/journeymaker/) is an innovative interactive experience that empowers families to create their own personalized journeys of the Art Institute of Chicago. Designed as a web application and developed for multi-touch screens, the interactive tool allows your family to create your very own tour of the museum. Choose one of eight storylines—like Superheroes, Time Travelers, or Strange and Wild Creatures—and then select works from the museum’s collection within that story. After you’ve made your selections, print out your personalized Journey Guide, which includes information, activities, and wayfinding directions. Then head into the museum for an art-filled adventure!
+[JourneyMaker](http://journeymaker.artic.edu/) is an innovative interactive experience that empowers families to create their own personalized journeys of the Art Institute of Chicago. Designed as a web application and developed for multi-touch screens, the interactive tool allows your family to create your very own tour of the museum. Choose one of eight storylines—like Superheroes, Time Travelers, or Strange and Wild Creatures—and then select works from the museum’s collection within that story. After you’ve made your selections, print out your personalized Journey Guide, which includes information, activities, and wayfinding directions. Then head into the museum for an art-filled adventure!
 
-JourneyMaker launched at the Art Institute of Chicago on July 1, 2016 as six multi-touchscreens in our Ryan Learning Center, along with a [desktop version](http://journeymaker.artic.edu/) available online. It's still in place today and is being maintained by a team of internal developers.
+JourneyMaker launched at the Art Institute of Chicago on July 1, 2016 as six multi-touch screens in our Ryan Learning Center, along with a [desktop version](http://journeymaker.artic.edu/) available online. It's still in place today and is being maintained by a team of internal developers.
 
 ## Features
 
-* Integration with your Collections API
+* Integration with your Public API
 * Bundles all CMS data to a JSON file for the frontend
 
 ## Overview
 
-JourneyMaker consists of two parts: a content authoring system written PHP utilizing Laravel and Twill CMS, and a public-facing frontend written in JavaScript. This repository contains the content authoring system. In order to deploy your own instance of JourneyMaker, you will also need to install the JourneyMaker Client:
+JourneyMaker consists of two parts: a content authoring system written in PHP utilizing Laravel and Twill CMS, and a public-facing frontend written in JavaScript. This repository contains the content authoring system. In order to deploy your own instance of JourneyMaker, you will also need to install the JourneyMaker Client:
 
 https://github.com/art-institute-of-chicago/journeymaker-client
 
-The JourneyMaker Client does not need to be installed on the same server or under the same domain as the CMS: as long as the client can access the assets stored in the CMS over HTTP ([CORS](http://stackoverflow.com/questions/20035101/no-access-control-allow-origin-header-is-present-on-the-requested-resource)), everything should work fine. For cross-domain development, you can use the [Allow-Control-Allow-Origin: \*](https://chrome.google.com/webstore/detail/allow-control-allow-origi/nlfbmbojpeacfghkpbjhddihlkkiljbi) Chrome extension.
+The JourneyMaker Client does not need to be installed on the same server or under the same domain as the CMS: as long as the client can access the assets stored in the CMS over HTTP ([CORS](http://stackoverflow.com/questions/20035101/no-access-control-allow-origin-header-is-present-on-the-requested-resource)), everything should work fine. For cross-domain development, you can use an Allow CORS browser extension.
 
 For brevity, throughout the rest of this repo's documentation, "JourneyMaker" refers to the public-facing frontend client. "JourneyMaker CMS" refers to the content authoring system, i.e. this repository.
 
@@ -37,7 +37,7 @@ In addition to Laravel PHP extension requirements you will also need either the
 
 The easiest way to get started locally is using [Laravel Herd](https://herd.laravel.com/).
 
-There is some additional content required in order for to get your CMS ready for the client. You'll need to add artworks and tie them to themes. Please follow the [User Documentation](USER-DOCUMENTATION.md) for further instructions.
+There is some content entry required in order to get your CMS ready for the client. You'll need to add artworks and tie them to themes. Please follow the [User Documentation](USER-DOCUMENTATION.md) for further instructions.
 
 If you install the JourneyMaker Client, you'll need to provide it the URL to the JSON document produced by the CMS. The following URL should be available with all your content bundled together:
 
@@ -47,40 +47,27 @@ http://your-journeymaker-cms.test/json/data.json
 
 ### Integration with your Collections API
 
-There is some functionality built in to retrieve artwork and gallery metadata from a collections API. You can go to `/admin/settings/aic-api` in your CMS to set the URLs for various queries to your API, but the parsing of the results is currently hardcoded. Take a look at the functions in [`aic_api.module`](sites/all/modules/custom/aic_api/aic_api.module) to make changes to reflect your API.
-
-Here are some examples of what your URLs might look like:
-
-```
-# Artwork query by ID URL
-http://api.yourmuseum.org/solr/select?fq=document_type:artwork-webcoll&q=object_id:{{pk}}&wt=json
-
-# Gallery query by name URL
-http://api.yourmuseum.org/solr/select?fq=document_type:gallery&wt=json&q=title_s:{{name}}
-
-# General artwork query URL
-http://api.yourmuseum.org/solr/select?fq=document_type:artwork-webcoll&q={{type}}:{{term}}&wt=json
-```
+There is some functionality built in to retrieve artwork and gallery metadata from an API. We've built scaffolding that will allow you to use Eloquent-like models that are backed by your API. You can configure the URI of your API in [`config/api.php`](config/api.php), and to dive deeper take a look at the `getArtworkApiData()` and `getGalleryApiData()` methods in the [Artwork model](app/Models/Artwork.php) and the `queryArtwork()` method on the [ArtworkController](app/Http/Controllers/Twill/ArtworkController.php).
 
 ### Caching
 
-We rely extensively on caching improve CMS response times and reduce the number of requests required to build the JSON output files.
+We rely extensively on caching to improve CMS response times and reduce the number of requests required to build the JSON output files.
 
-The Artwork model provides a static method (`cacheArtworkApiData`) to query the API and cache API results used to populate Artwork attributes. The API limits the number of IDs you can request to 100. The Artwork models are chunked into groups of 100 and the results of each Artwork model is cached individually using the API route to that specific Artwork (eg. `/api/v1/artworks/123`).
+The Artwork model provides a static method (`cacheArtworkApiData`) to query the API and cache API results used to populate Artwork attributes. The AIC API limits the number of IDs you can request to 100. The Artwork models are chunked into groups of 100 and the results of each Artwork model are cached individually using the API route to that specific Artwork (eg. `/api/v1/artworks/123`).
 
-**Hydrating Artwork with API Data**
+#### Hydrating Artwork with API Data
 
-When displaying an Artwork model in the CMS or generating the JSON output we rely on data from the API for some Artwork attributes.  The Artwork model contains a `__get` method, when a requested attribute is defined as coming from the API we return the API's value. First we check the cache for the Artwork and return the hit if one is found. When no API result is cached for the Artwork we query the API, cache the results, then return the data.
+When displaying an Artwork model in the CMS or generating the JSON output we rely on data from the API for some Artwork attributes.  The Artwork model contains a `__get` method, when a requested attribute is defined as coming from the API we return the API's value. First, we check the cache for the Artwork and return the hit if one is found. When no API result is cached for the Artwork we query the API, cache the results, then return the data.
 
 The `CacheJsonCommand` is scheduled to run every 5 minutes. This command starts by running `Artwork::cacheArtworkApiData`. The API data for each Artwork model is cached for 5 minutes. The CMS should never have to get API data on the fly. If you experience any performance issues double check the cron and `CacheJsonCommand` is running correctly.
 
 ## User Documentation
 
-For information on create and managing content within the CMS, please see the [User Documentation](USER-DOCUMENTATION.md).
+For information on creating and managing content within the CMS, please see the [User Documentation](USER-DOCUMENTATION.md).
 
 ## Contributing
 
-We encourage your contributions. Please fork this repository and make your changes in a separate branch. We like to use [git-flow](https://github.com/nvie/gitflow) to make this process easier.
+We encourage your contributions. Please fork this repository and make your changes in a separate branch.
 
 ```bash
 # Clone the repo to your computer
@@ -90,15 +77,15 @@ git clone https://github.com/your-github-account/journeymaker-cms.git
 cd journeymaker-cms
 
 # Start a feature branch
-git flow start feature yourinitials-good-description-issuenumberifapplicable
+git checkout -b feature/yourinitials-good-description-issuenumberifapplicable
 
 # ... make some changes, commit your code
 
 # Push your branch to GitHub
-git push origin yourinitials-good-description-issuenumberifapplicable
+git push origin feature/yourinitials-good-description-issuenumberifapplicable
 ```
 
-Then on github.com, create a Pull Request to merge your changes into our `develop` branch.
+Then on github.com, create a Pull Request to merge your changes into our `main` branch.
 
 This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its [terms](CODE_OF_CONDUCT.md).
 
@@ -156,11 +143,11 @@ Tests can be run using PHPUnit:
 composer test
 ```
 
-Tests use an in memory SQLite database.
+Tests use an in-memory SQLite database.
 
 ## Acknowledgments
 
-Design and Development by [Belle & Wissel Co](http://www.bwco.info/).
+Development by [Tighten Co](https://tighten.com/).
 
 ## Licensing
 

diff --git a/USER-DOCUMENTATION.md b/USER-DOCUMENTATION.md
@@ -2,7 +2,7 @@
 
 # JourneyMaker CMS User Documentation
 
-JourneyMaker CMS leverages [Twill](https://twillcms.com/) to build the easy-to-use system to add and edit content.
+JourneyMaker CMS leverages [Twill](https://twillcms.com/) to build an easy-to-use system to add and edit content.
 
 ## Navigation bar
 
@@ -18,6 +18,7 @@ The navigation contains the following links from left to right:
 | Themes | From Themes, you’ll navigate to add or edit themes, prompts, and associate  artworks existing artworks to prompts. |
 | Artworks | Artwork is organized here and can be searched and queried to add new artwork into the CMS. |
 | Directory | Themes and prompts are organized here in a list view as another way to easily review information. This page is not used for content entry. |
+| API Log | A log of changes to JourneyMaker artwork that have been made in the API. |
 | Media Library | The images that are uploaded to the CMS live here, e.g. if you upload an image on a form page such as an alternate image for artwork–it will live here. |
 | User Profile (‘Admin’) | User profile information lives here. |
 | Search | Global search is opened by clicking on the magnifying glass. |
@@ -39,7 +40,7 @@ When entering new content (e.g. a new artwork ) – that content will need to be
 **Keep in mind**
 
 - Artwork entries must be published to appear in the JSON output which is used by the frontend.
-- If artwork is not on view that will automatically not be available for the frontend.
+- If an artwork is published, if it is not on view it will automatically not be available for the frontend.
 - All translations must be entered in the CMS to appear in the JSON output that the frontend uses. If translations are not present, that content will not appear.
 - If an object is located in Regenstein Hall it will not appear in the JSON output.
 
@@ -61,7 +62,7 @@ You can not only add or edit new themes from this page, but also navigate to add
   - Guide Covert Art: (1125 x 1500)
   - Guide Covert Art (Home Companion): (1125 x 1500)
   - Backgrounds Image: (Min of 1920 x 1080)
-- Keep in mind, some of the above fields have a corresponding Spanish and Chinese translation form that also needs to be filled out with the translated fields. The language toggle lives on the top right of the screen. You can also toggle between languages using the language label next to the form label. Eg Title [EN]
+- Keep in mind, some of the above fields have a corresponding Spanish and Chinese translation form that also needs to be filled out with the translated fields. The language toggle lives on the top right of the screen. You can also toggle between languages using the language label next to the form label. E.g., Title [EN]
 - Each field needs all three languages to be filled out in order to appear in the output JSON and be available to JourneyMaker.
 
 Once done with the content entry, save as a draft or change the publication status with the toggle.
@@ -83,10 +84,10 @@ Once done with the content entry, save as a draft or change the publication stat
 
 - Once you click on the ‘Add Artwork’ button – the artwork form will appear underneath the prompt. The Artwork form contains the following fields:
   - Artwork - Clicking on Add Artwork here, you can attach an artwork here after searching for it.
-  - Detail Narrative - Interface) (limit of 100 characters + 10 for padding for a total of 110).
-  - Look Again - Journey Guide) (limit of 125 characters + 10 for padding for a total of 135).
-  - Activity Template  - Journey Guide): Dropdown choice.
-  - Activity Instructions - Journey Guide) (limit of 128 characters + 10 for padding for a total of 138).
+  - Detail Narrative (Interface) - limit of 100 characters + 10 for padding for a total of 110.
+  - Look Again (Journey Guide) - limit of 125 characters + 10 for padding for a total of 135.
+  - Activity Template (Journey Guide) - Dropdown choice.
+  - Activity Instructions (Journey Guide) - limit of 128 characters + 10 for padding for a total of 138.
 - Additional artworks can be added to associate with that artwork and prompt by clicking on the blue ‘Add Artwork’ button at the bottom of the form.
 - As on all form pages:
   - The translation toggle sits on the top right of the page, so the prompt content can be added in English, Spanish and Chinese.
@@ -97,10 +98,10 @@ Once done with the content entry, save as a draft or change the publication stat
 
 - To edit an existing theme, navigate to the Themes page from the main navigation menu.
 - From the Themes landing page, you’ll see a table that lists the existing theme titles, prompts, and languages.
-- Click into any of the themes (e.g ‘Let’s Play’) to pull up the existing theme to change any of the content entry in the form.
+- Click into any of the themes (e.g., ‘Let’s Play’) to pull up the existing theme to change any of the content entry in the form.
 - Clicking into a theme form will also provide the Prompt navigation, allowing you to make edits to the Prompt form and the artwork it is associated with.
 - Click into the prompt that you would like to edit and the Prompt form will appear.
-- Within prompts, you can add or delete any artwork blocks and drag and drop the order of them as shown in the screenshot below.
+- Within prompts, you can add or delete any artwork blocks and drag and drop the order of them.
 
 ## Artworks
 To add new artwork to the CMS, you will navigate to the Artworks page and pull that artwork into the CMS by running a query. The artwork available in the CMS is also organized here and can be searched.
@@ -139,9 +140,9 @@ Images uploaded to the CMS are organized here such as alternative images to artw
 
 ## User Profile
 
-Currently, Twill is configured so that only admin users exist within the CMS.
+Admins have the ability to add new users to the CMS and manage existing ones. Click "CMS Users" to get started.
 
-**Admins have:**
+**Admins also have:**
 
 - Access privileges to update and publish any piece of content within the CMS.
 - Ability to update their email and preferred language under the ‘Profile’ tab by clicking the down arrow on their username.