← Documentation Team

Statement Management


Managing the monthly Banno statement

The monthly statement process consists of three stages and involves reviewers from numerous teams—Product Management, Operations, Documentation, and Developer Relations.

Gathering content

Rounding up statement content can often prove difficult, so it’s critical to call for content early enough to have all topics—and most details—in hand by the 15th of each month.

Content doc prep

To prepare the content doc, open the Banno Statements folder on Google Drive, and then duplicate either the previous month’s statement or the Statement content doc template.

Call for content

Once the content doc is prepared, it’s time to request statement content in the #team-monthly-statement Slack channel.

INSERT IMAGE
Figure 1: Example call for statement content

Your post in #team-monthly-statement should include these elements, as seen in the example above:

  • Heading: 📣 Month Statement: Call for Content
  • Due date: Specify that content topics are due by the 13 - 15 of the month, or note the date and reason it differs that month.
  • Any notes: Include any details or special circumstances contributors need to know.
  • @ mentions: Tag our contributors and ask for any topics they want included:
    • Ops topics: @Abby Wood, @sheena, @Derek, @heather, and @holly often ask us to address customer issues that are causing concern.
    • Toolkit topics: @Jaime Lopez typically has ‘Toolkit Corner’ news to include.
    • Banno Content topics: @sheahardin occasionally has news to include.
    • Documentation updates: @brittany or @wilLiff will typically provide a list of updates on the Banno Knowledge Base (both the internal KB and the customer-facing KB), and work with an ECS rep to gather WebHelp updates made on the Banno Help Center (public-facing how-to guides for Banno customers and their end users).
    • PM topics: The @pm team provides the majority of statement content—including input on the two to three articles that should feature images, which we then request from Design in the #team-product-design Slack channel.

Getting set up & editing

For the most efficient process, try and make sure the content is in as good a place as possible prior to doing anything with HTML. Get content approval from PMs and Banno voice review from Lacey. Once all edits have been made, hack away (see below).

Updating Github files doc prep

We need to grab the latest Banno website files on Github and create a new branch. To do so, open terminal and complete these steps:

  1. Enter cd ~/[your-local-folder]/banno.com, which will connect to the Banno.com repo stored on your local machine.
  2. Enter git checkout -b [month_year_statement_branch], which will create and switch to a new local branch that you can safely edit.
    Note: If you already created a branch on Github and you need to pull its content to your local machine, enter the following command instead: git checkout [branch name]

Resources
Here are a couple of troubleshooting resources to use when working with Github:

Run jekyll serve

To preview your changes in a locally hosted browser (i.e., viewable only on your local machine), open Terminal and complete these steps:

  1. Enter cd ~/[your-local-folder]/banno.com
  2. Enter git pull
  3. Enter Bundle exec jekyll serve
  4. Open a browser window and enter this URL: localhost:4000

You're now ready to preview the latest content changes in near-real time. Simply save the changes on your local machine and then refresh the browser window.

Editing the statement HTML file

To edit the statement on your local machine, follow these steps:

  1. In Finder, navigate to ~/[your-local-folder]/banno.com, and open the folder in a text editor such as Atom.
  2. In the text editor, drill down to the _posts folder and duplicate the most-recent statement file (which is an HTML file).
  3. Edit the HTML file as needed.
    1. Change the date, which is controlled by the file name: Simply update the month (e.g., 2022-07-01-index.md would become 2022-08-01-index.md).
    2. Update content, adjust the placement of articles as needed to ensure the two columns are roughly the same height, and intermix articles with images.
  4. Save your changes.
  5. Visit or refresh the localhost:4000 URL in your browser and preview the changes.

To prepare and add an image to the statement:

  1. Save two, compressed versions of each image:
    • image_name.png: The 1x version should be 570px wide, and the height can vary.
    • image_name@2x.png: The 2x version should be 1140px wide, and the height can vary.
  2. In your text editor, open img > statements and add the two versions of the image.
  3. Return to the statement HTML file, and ensure that each image path corresponds with the name of the image you added, as seen in this example:
    Picture of Offline mode screen with Show status feature included.

Once you’re happy with the complete draft, it’s time to commit your changes to our UAT environment.

Committing changes to UAT

To push your local branch and its edited content to the shared Banno.com repo on Github, open a new Terminal tab and enter the following commands:

  1. git status
  2. git add .
  3. git status
      Note: When the font turns green, the changes have been staged.
  4. git commit -m '[description of changes]'
      Example description: '[polished draft for initial review]'
  5. git push origin [branch name]
      Example branch name: [banno-statement-august-2022]

To deploy your changes to Banno UAT, use Github:

  1. Open our Github files and select your branch.
  2. Click Compare & pull request.
  3. Enter a description and click Create pull request.
  4. After the Github checks have completed, click Merge pull request.

Before deploying your statement branch to our production environment, you’ll need to request reviews from our designated approvers.

Call for reviews

Once the statement is prepped and ready for review, you can share it with approvers in the #team-monthly-statement Slack channel.

INSERT IMAGE
Figure 2: Example call for statement review

Your post in #prod-monthly-statement should include these elements, as seen in the example above:

  • Heading: 📣 Month Statement: Call for Review
  • Due date: Specify that reviews are due by 18th - 20th of the month, or note the date and reason it differs that month.
  • Any notes: Include any details that approvers need to know.
  • @ mentions: Tag our approvers:

The review process often involves a lot of discussion, which can make reviews take longer than one might expect. Leave yourself plenty of review time before the statement must be published, and always remember to carefully test each link as well as ensure that all linked articles are from the public-facing Knowledge Base (i.e., only include KB articles from the knowledge.banno.com subdomain rather than the internal-facing docs.banno.com subdomain).

Once other PMs have signed off on their articles and you have two approvals from Ops, one from Toolkit, and one from Documentation, you’re ready to deploy the statement to production.

Preparing for production deploy

Before you send the statement to the Banno.com production environment, make sure you dot the eyeballs and such:

  1. In the Operation team’s Google Drive, draft a statement announcement email, which Support will send to customers.
  2. In the #team-monthly-statement Slack channel, ping Support (typically Holly Miner) to review your email draft and double check all links and URLs so it’s ready to send once the statement is approved and published.

For best results, give the Ops team a few days notice. Note, however, that this has proven to be a lofty goal so far.

Deploying to production

With the necessary approvals in hand, it’s time to deploy the statement to the production environment, Banno.com:

  1. In the #team-product-marketing Slack channel, click the Ready to send production release notes link, which will look like this:
    banno-com/master 1.XXX.0 (involved: Your-Name) Ready to send production. release notes for banno.com x.xxx.x. Please approve.
  2. In the Jenkins page that opens, click Proceed.
  3. Return to the #team-product-marketing Slack channel, and wait a couple minutes until you see the Sent release notes link, which will look like this:
    banno-com/master 1.XXX.0 (involved: Your-Name) Sent release notes for banno.com (1.XXX.0).
  4. In the #org-deployments channel, post an approval request similar to this, which references the subject line of the email sent to approvers after you completed step 1:
    @approvers can I please get two on [For Approval] Production banno.com Release - Version 1.xxx.0?
  5. After receiving the necessary approvals, return to the #org-deployments Slack channel and add a ✅ reaction to your approval request.
  6. In the #team-product-marketing channel, click the newly available Deploy to production link, which will look like this:
    banno-com/master 1.292.0 (involved: Your-Name) Deploy banno-com (1.292.0) to production?
  7. In the Jenkins page that opens, click Proceed.
    Note: If presented with an option to set a Canary weight, leave the text field empty, select the readyToDeploy checkbox, and then click Proceed.
  8. After 15 - 20 minutes, return to the #team-product-marketing channel, and check for a "successful deploy" message that will look like this:
    banno-com/master 1.555.0 (involved: Submitter-Name) Successfully deployed banno-com (1.555.0) to production kubernetes.
    Note: If you don't see the success message, open the Jenkins page (from step 7) again, and then click Proceed.

Updating the dashboard in People

Right after the statement has finished deploying to production, you’ll need to update the statement details displayed on the Banno People™ dashboard:

  1. In Slack, head to #org-firefighter-requests and post something like FF please.
  2. Once your request is acknowledged, which happens automatically, ensure that you’re logged in as your Banno (admin) user and navigate to the hidden Login Dashboard config screen: https://banno.com/a/settings/24/config/login-dashboard
  3. Update the Date, StatementURL, and Title fields based on the current month.
  4. Update the ImageURL field, using the URL path of your favorite image from the current statement.
  5. Save your changes and navigate to People on Banno DevBank, Garden, or even a customer instance to ensure that your changes were successfully saved.
    Note: It’s often necessary to refresh the dashboard screen multiple times before you see the changes take hold. You may even need to switch institutions a couple times, as there seems to be some sort of caching issue that delays propagation.

Celebrating a job well done

You did it! You jumped through all the hoops, rallied all the troops, fixed every oops, and pushed and pulled your way through the Terminal minefield to publish the scoop! This accomplishment alone is worth celebrating, and that’s not even counting the collective team efforts behind the feature release and enhancements the latest statement covers.

Now that you’ve made a statement, you get to drop the 🎤 in a handful of Slack channels:

  1. Write a brief announcement blurb, which should highlight the most newsworthy articles and include a link to the statement.
  2. Post the announcement in these channels:

That's it. Nice work!