Oct 11 2018
Oct 11

Authors are eager to learn, and a content-focused community is forming. But there’s still work to do.

Video showing highlights of speakers, presenters, and attendees interacting at ConCon 2018.

When you spend most of your time focused on how to serve constituents on digital channels, it can be good to simply get some face time with peers. It’s an interesting paradox of the work we do alongside our partners at organizations across the state. Getting in a room and discussing content strategy is always productive.

That was one of the main reasons behind organizing the first ever Massachusetts Content Conference (ConCon). More than 100 attendees from 35 organizations came together for a day of learning and networking at District Hall in Boston. There were 15 sessions on everything from how to use Mayflower — the Commonwealth’s design system — to what it takes to create an awesome service.

Graphic showing more than 100 attendees from 50 organizations attended 15 sessions from 14 presenters at ConCon 2018.

ConCon is and will always be about our authors, and we’re encouraged by the feedback we’ve received from them so far. Of the attendees who responded to a survey, 93% said they learned about new tools or techniques to help them create better content. More so, 96% said they would return to the next ConCon. The average grade attendees gave to the first ever ConCon on a scale of 1 to 10 — with 1 being the worst and 10 the best — was 8.3.

Our authors were engaged and ready to share their experiences, which made for an educational environment, for their peers as well as our own team at Digital Services. In fact, it was an eye opening experience, and we took a lot away from the event. Here are some of our team’s reflections on what they learned about our authors and our content needs moving forward.

We’re starting to embrace data and feedback

“The way we show feedback and scores per page is great but it doesn’t help authors prioritize their efforts to get the biggest gain for their constituents. We’re working hard to increase visibility of this data in Drupal.”

— Joe Galluccio

Katie Rahhal, Content Strategist
“I learned we’re moving in the right direction with our analysis and Mass.gov feedback tools. In the breakout sessions, I heard over and over that our content authors really like the ones we have and they want more. More ways to review their feedback, more tools to improve their content quality, and they’re open to learning new ways to improve their content.”

Christine Bath, Designer
“It was so interesting and helpful to see how our authors use and respond to user feedback on Mass.gov. It gives us a lot of ideas for how we can make it easier to get user feedback to our authors in more actionable ways. We want to make it easy to share constituent feedback within agencies to power changes on Mass.gov.”

Embedded tweet from @MassGovDigital highlighting a lesson on good design practices from ConCon 2018.

Joe Galluccio, Product Manager
“I learned how important it is for our authors to get performance data integrated into the Drupal authoring experience. The way we show feedback and scores per page is great but it doesn’t help authors prioritize their efforts to get the biggest gain for their constituents. We’re working hard to increase visibility of this data in Drupal.”

Our keynote speaker gave a great use case for improving user journeys

Bryan Hirsch, Deputy Chief Digital Officer
“Having Dana Chisnell, co-founder of the Center for Civic Design, present her work on mapping and improving the journey of American voters was the perfect lesson at the perfect time. The page-level analytics dashboards are a good foundation we want to build on. In the next year, we’re going to research, test, and build Mass.gov journey analytics dashboards. We’re also spending this year working with partner organizations on mapping end-to-end user journeys for different services. Dana’s experience on how to map a journey, identify challenges, and then improve the process was relevant to everyone in the room. It was eye-opening, enlightening, and exciting. There are a lot of opportunities to improve the lives of our constituents.”

Want to know how we created our page-level data dashboards? Read Custom dashboards: Surfacing data where Mass.gov authors need it

Embedded tweet from @epubpupil highlighting her positive thoughts on Dana Chisnell’s keynote presentation on mapping and improving the journey of American voters.

The Mayflower Design System is a work in progress

“It’s great to see there’s a Mayflower community forming among stakeholders in different roles across state government. ”

— Minghua Sun

Sienna Svob, Developer and Data Analyst
“We need to work harder to build a Mayflower community that will support the diversity of print, web, and applications across the Commonwealth. Agencies are willing and excited to use Mayflower and we need to harness this and involve them more to make it a better product.”

Minghua Sun, Mayflower Product Owner
“I’m super excited to see that so many of the content authors came to the Mayflower breakout session. They were not only interested in using the Mayflower Design System to create a single face of government but also raised constructive questions and were willing to collaborate on making it better! After the conference we followed up with more information and invited them to the Mayflower public Slack channel. It’s great to see there’s a Mayflower community forming among stakeholders in different roles across state government. ”

All digital channels support content strategy

Sam Mathius, Digital Communications Strategist
“It was great to see how many of our authors rely on digital newsletters to connect with constituents, which came up during a breakout session on the topic. Most of them feel like they need some help integrating them into their overall content strategy, and they were particularly excited about using tools and software to help them collect better data. In fact, attendees from some organizations mentioned how they’ve used newsletter data to uncover seasonal trends that help them inform the rest of their content strategy. I think that use case got the analytics gears turning for a lot of folks, which is exciting.”

Authors are eager and excited to learn and share

“I’d like to see us create more opportunities for authors to get together in informal sessions. They’re such a diverse group, but they share a desire to get it right.”

— Fiona Molloy

Shannon Desmond, Content Strategist
“I learned that the Mass.gov authors are energetic about the new content types that have been implemented over the past 8 months and are even more eager to learn about the new enhancements to the content management system (CMS) that continue to roll out. Furthermore, as a lifelong Massachusetts resident and a dedicated member of the Mass.gov team, it was enlightening to see how passionate the authors are about translating government language and regulations for constituents in a way that can be easily and quickly understood by the constituents of the State.”

Fiona Molloy, Content Strategist
“Talking to people who came to ConCon and sitting in on various sessions, it really struck me how eager our content authors are to learn — whether from us here at Digital Services or from each other. I’d like to see us create more opportunities for authors to get together in informal sessions. They’re such a diverse group, but they share a desire to get it right and that’s really encouraging as we work together to build a better Mass.gov.”

Embedded tweet from @MassGovDigital highlighting a session from ConCon 2018 in which content authors offered tips for using authoring tools on Mass.gov.

Improving content and author support is a continual process

Adam Cogbill, Content Strategist
“I was reminded that one of the biggest challenges that government content authors face is communicating lots of complex information. We need to make sure we understand our audience’s relationships to our content, both through data about their online behavior and through user testing.”

Greg Derosiers, Content Strategist
“I learned we need to do a better job of offering help and support. There were a number of authors in attendance that didn’t know about readily-available resources that we had assumed people just weren’t interested in. We need to re-evaluate how we’re marketing these services and make sure everyone knows what’s available.”

Embedded tweet from @MassGovDigital highlighting the start of ConCon 2018.

Thinking about hosting your own content conference? Reach out to us! We’d love to share lessons and collaborate with others in the civic tech community.

Oct 10 2018
Oct 10

Variety of content and the need for empathy drive our effort to simplify language across Mass.gov

Nearly 7 million people live in Massachusetts, and millions more visit the state each year. These people come from different backgrounds and interact with the Commonwealth for various reasons.

Graphic showing more than 3 million visitors go to Mass.gov each month.

We need to write for everyone while empathizing with each individual. That’s why we write at a 6th grade reading level. Let’s dig into the reasons why.

Education isn’t the main factor

The Commonwealth has a high literacy rate and a world-renowned education network. From elementary school to college and beyond, you can get a great education here.

We’re proud of our education environment, but it doesn’t affect our readability standards. Navigating the Women, Infants, and Children (WIC) Nutrition Program might be challenging for everyone.

Complexity demands simplicity

People searching for nutrition services are doing so out of necessity. They’re probably frustrated, worried, and scared. That affects how people read and retain information.

Learn about our content strategy. Read the 2017 content team review.

This is the case for many other scenarios. Government services can be complicated to navigate. Our job is to simplify language. We get rid of the white noise and focus on essential details.

Time is not on our side

You don’t browse Mass.gov in your free time. It’s a resource you use when you have to. Think of it as a speedboat, not a cruise ship. They’ll both get you across the water, just at different speeds.

Graphic showing desktop visitors to Mass.gov look at more pages and have longer sessions than mobile and tablet visitors.

Mass.gov visitors on mobile devices spend less time on the site and read fewer pages. The 44% share of mobile and tablet traffic will only increase over time. These visitors need information boiled down to essential details. Simplifying language is key here.

Exception to the rule

A 6th-grade reading level doesn’t work all the time. We noticed this when we conducted power-user testing. Lawyers, accountants, and other groups who frequently use Mass.gov were involved in the tests.

These groups want jargon and industry language. It taught us that readability is relative.

Where we are today

We use the Flesch-Kincaid model to determine reading level in our dashboards. It accounts for factors like sentence length and the number of syllables in words.

This is a good foundation to ensure we consistently hit the mark. However, time is the most important tool we have. The more content we write, the better we’ll get.

Writing is a skill refined over time, and adjusting writing styles isn’t simple. Even so, we’re making progress. In fact, this post is written at a 6th grade reading level.

Oct 09 2018
Oct 09

Helping content creators make data-driven decisions with custom data dashboards

Our analytics dashboards help Mass.gov content authors make data-driven decisions to improve their content. All content has a purpose, and these tools help make sure each page on Mass.gov fulfills its purpose.

Before the dashboards were developed, performance data was scattered among multiple tools and databases, including Google Analytics, Siteimprove, and Superset. These required additional logins, permissions, and advanced understanding of how to interpret what you were seeing. Our dashboards take all of this data and compile it into something that’s focused and easy to understand.

We made the decision to embed dashboards directly into our content management system (CMS), so authors can simply click a tab when they’re editing content.

GIF showing how a content author navigates to the analytics dashboard in the Mass.gov CMS.

How we got here

The content performance team spent more than 8 months diving into web data and analytics to develop and test data-driven indicators. Over the testing period, we looked at a dozen different indicators, from pageviews and exit rates to scroll-depth and reading grade levels. We tested as many potential indicators as we could to see what was most useful. Fortunately, our data team helped us content folks through the process and provided valuable insight.

Love data? Check out our 2017 data and machine learning recap.

We chose a sample set of more than 100 of the most visited pages on Mass.gov. We made predictions about what certain indicators said about performance, and then made content changes to see how it impacted data related to each indicator.

We reached out to 5 partner agencies to help us validate the indicators we thought would be effective. These partners worked to implement our suggestions and we monitored how these changes affected the indicators. This led us to discover the nuances of creating a custom, yet scalable, scoring system.

Line chart showing test results validating user feedback data as a performance indicator.

For example, we learned that a number of indicators we were testing behaved differently depending on the type of page we were analyzing. It’s easy to tell if somebody completed the desired action on a transactional page by tracking their click to an off-site application. It’s much more difficult to know if a user got the information they were looking for when there’s no action to take. This is why we’re planning to continually explore, iterate on, and test indicators until we find the right recipe.

How the dashboards work

Using the strategies developed with our partners, we watched, and over time, saw the metrics move. At that point, we knew we had a formula that would work.

We rolled indicators up into 4 simple categories:

  • Findability — Is it easy for users to find a page?
  • Outcomes — If the page is transactional, are users taking the intended action? If the page is focused on directing users to other pages, are they following the right links?
  • Content quality — Does the page have any broken links? Is the content written at an appropriate reading level?
  • User satisfaction — How many people didn’t find what they were looking for?
Screenshot of dashboard results as they appear in the Mass.gov CMS.

Each category receives a score on a scale of 0–4. These scores are then averaged to produce an overall score. Scoring a 4 means a page is checking all the boxes and performing as expected, while a 0 means there are some improvements to be made to increase the page’s overall performance.

All dashboards include general recommendations on how authors can improve pages by category. If these suggestions aren’t enough to produce the boost they were looking for, authors can meet with a content strategist from Digital Services to dive deeper into their content and create a more nuanced strategy.

GIF showing how a user navigates to the “Improve Your Content” tab in a Mass.gov analytics dashboard.

Looking ahead

We realize we can’t totally measure everything through quantitative data, so these scores aren’t the be-all, end-all when it comes to measuring content performance. We’re a long way off from automating the work a good editor or content strategist can do.

Also, it’s important to note these dashboards are still in the beta phase. We’re fortunate to work with partner organizations who understand the bumps in the proverbial development road. There are bugs to work out and usability enhancements to make. As we learn more, we’ll continue to refine them. We plan to add dashboards to more content types each quarter, eventually offering a dashboard and specific recommendations for the 20+ content types in our CMS.

Oct 09 2018
Oct 09

I recently worked with the Mass.gov team to transition its development environment from Vagrant to Docker. We went with “vanilla Docker,” as opposed to one of the fine tools like DDev, Drupal VM, Docker4Drupal, etc. We are thankful to those teams for educating and showing us how to do Docker right. A big benefit of vanilla Docker is that skills learned there are generally applicable to any stack, not just LAMP+Drupal. We are super happy with how this environment turned out. We are especially proud of our MySQL Content Sync image — read on for details!

Pretty docks at Boston Harbor. Photo credit.

Docker compose

The heart of our environment is the docker-compose.yml. Here it is, then read on for a discussion about it.

Developers use .env files to customize aspects of their containers (e.g. VOLUME_FLAGS, PRIVATE_KEY, etc.). This built-in feature of Docker is very convenient. See our .env.example file:

MySQL content sync image

The most innovative part of our stack is the mysql container. The Mass.gov Drupal database is gigantic. We have tens of thousands of nodes and 500,000 revisions, each with an unholy number of paragraphs, reference fields, etc. Developers used to drush sql:sync the database from Prod as needed. The transfer and import took many minutes, and had some security risk in the event that sanitization failed on the developer’s machine. The question soon became, “how can we distribute a mysql database that’s already imported and sanitized?” It turns out that Docker is a great way to do just this.

Today, our mysql container builds on CircleCI every night. The build fetches, imports, and sanitizes our Prod database. Next, the build does:

That is, we commit and push the refreshed image to a private repository on Docker Cloud. Our mysql image is 9GB uncompressed but thanks to Docker, it compresses to 1GB. This image is really convenient to use. Developers fetch a newer image with docker-compose pull mysql. Developers can work on a PR and then when switching to a new PR, do a simple ahoy down && ahoy up. This quickly restores the local Drupal database to a pristine state.

In order for this to work, you have to store MySQL data *inside* the container, instead of using a Docker Volume. Here is the Dockerfile for the mysql image.

Drupal image

Our Drupal container is open source — you can see exactly how it’s built. We start from the official PHP image, then add PHP extensions, Apache config, etc.

An interesting innovation in this container is the use of Docker Secrets in order to safely share an SSH key from host to the container. See this answer and mass_id_rsa in the docker-compose.yml above. Also note the two files below which are mounted into the container:

Configure SSH to use the secrets file as private key Automatically run ssh-add when logging into the container

Traefik

Traefik is a “cloud edge router” that integrates really well with docker-compose. Just add one or two labels to a service and its web site is served through Traefik. We use Traefik to provide nice local URLs for each of our services (www.mass.local, portainer.mass.local, mailhog.mass.local, …). Without Traefik, all these services would usually live at the same URL with differing ports.

In the future, we hope to upgrade our local sites to SSL. Traefik makes this easy as it can terminate SSL. No web server fiddling required.

Ahoy aliases

Our repository features a .ahoy.yml file that defines helpful aliases (see below). In order to use these aliases, developers download Ahoy to their host machine. This helps us match one of the main attractions of tools like DDev/Lando — their brief and useful CLI commands. Ahoy is a convenience feature and developers who prefer to use docker-compose (or their own bash aliases) are free to do so.

Bells and whistles

Our development environment comes with 3 fine extras:

  • Blackfire is ready to go — just run ahoy blackfire [URL|DrushCommand] and you’ll get back a URL for the profiling report
  • Xdebug is easily enabled by setting the XDEBUG_ENABLE environment variable in a developer’s .env file. Once that’s in place, the PHP in the container will automatically connect to the host’s PHPStorm or other Xdebug client
  • A chrome-headless container is used by our suite which incorporates Drupal Test Traits — a new open source project we published. We will blog about DTT soon

Wish list

Of course, we are never satisfied. Here are a couple issues to tackle:

Oct 09 2018
Oct 09

A straightforward mission doesn’t always mean there’s a simple path. When we kicked off the Mass.gov redesign, we knew what we wanted to create: A site where users could find what they needed without having to know which agency or bureaucratic process to navigate. At DrupalCon Baltimore in 2017, we shared our experience with the first nine months of the project building a pilot website with Drupal 8, getting our feet wet with human-centered (AKA “constituent-centric”) design, and beginning to transform the Mass.gov into a data-driven product.

Oct 09 2018
Oct 09

Structured content is central to the content strategy for our new Drupal-based Mass.gov. So is the idea of a platform-agnostic design that can be reused across our diverse ecosystem of web applications, to encourage a consistent look, feel, and user experience. We’re not the only ones with these priorities for our new digital platform. So we can’t be the only ones wrestling with the unsolved authoring experience implications either. This blog post is an attempt to articulate the basic problem and share our best, latest idea for one possible solution. As the saying goes, ‘If you want to go fast, go alone. If you want to go far, go together.’ We want to go far. If you like our idea, or if you have other possible solutions or insights, please share them with us in comments below, or by tweeting at us @massgov, or contact me at @bryanhirsch. Let’s go together.

Problems:

Drupal has made major strides toward improving the content authoring experience in recent years: Acquia’s Spark project in Drupal 7, Quick Edit in Drupal 8, and Edward Faulkner’s integrations with Ember. But (1) our vendors for Mass.gov have unanimously dissuaded us from leveraging these innovations in our new authoring experience because with complex data models it’s costly and highly customized to make in-place editing through the front end work. (2) This challenge is compounded by the desire to keep our design portable across diverse web properties, which means we want to keep Drupal’s Quick Edit markup out of our Pattern Lab-based component library. Additionally, (3) if we get structured content right, our Mass.gov content will be reused in applications we don’t control (like Google’s knowledge graph) and in an increasing number of government website via APIs. It’s both cost prohibitive and practically impossible to create frontend authoring UIs for each of these applications. That said, if we move authoring away from the front end in-place editing experience, (4) authors still need detailed context to visualize how different pieces of content will be used to write good content.

Here’s one possible solution we’re interested to explore that seems like it should address the four issues outlined above: Move high-fidelity live previews to the backend authoring experience, displayed alongside the content editing form as visualized in the designs below.

Visual design of possible UI for live preview of different components from the Pattern Lab-based Mayflower component library, incorporated into the backend Mass.gov authoring experience. View additional designs here.

By showing authors examples of how different pieces of content might be used and reused, we can give writers enough context to write meaningful structured content. But maybe we only need to give authors enough examples to have reasonable interactions with all the different content form fields. If this works, then we don’t have to try and keep up with an infinitely growing and changing landscape of possible new frontends. Pattern Kit (here) and Netlify CMS (here) both offer working, open-source, examples of how this authoring experience could work.

Mass.gov is not a “decoupled Drupal” ecosystem yet. Our API strategy is in its infancy. We know other people with much more experience are thinking about the same issues. Maybe some are even writing code and actively working to develop solutions. If this is you, we’d love to hear from you, to know how you’re approaching these problems, and to learn from anything you’ve tried here.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web