< Back to 2020 samples

A deep dive into writing helpful conceptual topics

Let's talk about conceptual topics. Those standalone topics that answer the questions “what is this thing” and “what is it for?”

Let's nerd out.

Why am I interested in conceptual topics?

1. They are some of the most-viewed content across our in-product documentation.
2. We hear frequently from customers that they struggle mapping Atlassian product concepts to their team's practices.
3. They're central to our mission as a content design organization. They connect the dots of our point solutions to help our customers understand why they should learn and use different facets of our products.

This is a long post. A deeeep dive. You might want to save it for when you have time.

If you’re short on time and want some quick tips, check out the rubric at the end of the post. It may help you assess your conceptual topics.

Our writers come from different backgrounds

Let's jump back to basics for a second and think about the our industry from 1000 ft – for kicks and for context. We come from a variety of backgrounds:

User interface or user experience writing centers itself around task completion within software products. UX writers closely align themselves with UX designers. They're great at testing and formulating micro copy that increases task completion and decreases the time it takes to complete tasks in their products. In simple terms, they're focused on what software users encounter.

Similarly, media and marketing writers look at the what in business writing. They focus on "funnel" metrics and click-through rates, search engine optimization, entrances and bounces. These signals direct them to write messages that increase engagement with products or services.

Technical writing deals with functional, instructional writing. Technical writers are great at going deep into the inner workings of complex products to expose all the wonderful ways to use them. More plainly, they're focused on concise instructions on how to perform a task.

Similarly, instructional design and education writing focus on how to do something. Educators often instinctively check for understanding (which is difficult to do in our products and on our support websites).

We need more transactional writing

One of the most important writing skills we can all lean on regardless of our backgrounds is transactional writing, a core writing competency for content designers.

Transactional writing is the art and practice of persuasive writing used to illicit transactions from readers that achieve their personal goals and our business goals.

Transactional writing answers a common reader questions: “so what?” and “why should I care?”

The so what aspect of transactional writing is critical to writing helpful concept topics, especially with products that are as powerful and flexible as Atlassian's.

As content designers, we need to:

• quickly express the value of each concept in our products and services
• explain how Atlassian concepts map to our customers' use cases and industry practices
• explain how Jira concepts map to agile practices
• explain how Jira Service Management concepts map to ITIL best practices

And, more importantly, we need to explain why they should transform the way they work by using our products.

Our customers want more transactional writing

When we launched in-product help, we saw that help seekers more frequently read conceptual topics (what is X thing) than procedural topics (how to do X thing). In fact 13 of the 15 most-read in-product help topics are conceptual topics.

Our customers self-report that in-product help is generally more helpful than our external support sites. It's not a big leap that these concepts are impactful to our customers' success.

We believe that when users understand why they should use a feature and how it can benefit them, they’re more likely to buy-in and use that feature.

There's a strong correlation between people who read conceptual information about features in our products and increased, longterm engagement with those features. For example, we saw that people who read the topic "what is the backlog?" viewed the backlog more over a longer period of time.

Interestingly, the effect was more pronounced on older users than on new users (source).

Speaking of new users, the Research and Insights team ran a longitudinal study on evaluators, called "accompanied activations", where they watched 40 evaluators try to understand Jira over 5 months. They found we're making too many assumptions about the knowledge of our customers.

The current ‘on-boarding experience’ assumes evaluators know: which Jira, which apps, and how Jira works...Evaluators who are familiar with agile are not necessarily familiar with Jira concepts. While those aware of agile are often more likely to come across some familiar concepts and terminology (story points, user stories), the Jira legend is neither easily visible within Jira nor easy to find via Google...Evaluators feel like they need to de-code the Jira pattern. They can detect that some kind of pattern exists e.g. Epic versus Story versus Task, Story points, Assignee...but what does it all mean and how does it fit together?...We place a lot of onus on the evaluator having loads of patience and determination to figure stuff out. Why do we assume so much prior knowledge exists? (source)

A tale of two concepts

To help demystify good conceptual writing, let's analyze two conceptual topics: one healthy topic, and one not-so-healthy topic.

After this analysis, we'll have a sense of what's working and what isn't, and can create a framework for evaluating content while we're drafting, reviewing, and revising.

A healthy conceptual topic

Start with the good. Things that work well are usually less fruitful to pull from because if we're doing our jobs correctly, you'd never notice we were doing anything at all.

To help get a peek at what good means for conceptual topics, I've chosen to analyze the in- product topic "What is the backlog?". It was the most-viewed in-product conceptual topic with the highest average helpfulness rating.

While its views have wobbled a bit, this topic has maintained a healthy rating between 72% and 88% for the past 5 months.

Some general information about this topic:

• Its 189 words long.
• It sits on a 7th grade reading level (Fleisch Kincaid)
• It can be read in just under a minute (~45sec)

The structure of this concept looks something like this:

• Title, in the form of a question
• Definition in plain terms
• Value statement/overall best practice
• Industry-specific use case examples

The title is written in the form of a question, following our guidance. This differentiates the topic from procedures or references. Recognizing this pattern (questions = concept topics), we can maintain our readers expectations of what content this topic contains. Instinctively, readers learn that if they want conceptual information, they should look for topics titled in the form of a question. This effect is greatly diminished if we're inconsistent.

The topic begins with a definition of a backlog in plain terms. In Contentful, this is actually a reusable component. Wherever we need to define the term "backlog", readers should see this definition. That definition provides the expected outcome of the concept in real life ("a dedicated space for defining and prioritizing work"). And, it avoids using a Jira term or other jargon to define it.

After the definition is an explanation of the value of the concept and how the concept relates to the reader's real life ("plan work in advance so that your team members can quickly jump on the most important tasks when they’re ready.") This answers the question: so what? Why do I, as a reader, care about this concept?

Tip: The phrase "so that" is key here. There’s an easy format you can steal: Do X so that Y. This type of wording can help you practice getting down to value statements that motivate people to try features and grok our products.

Then, the topic provides how this concept fits into industry methodology or specific use cases. It explains the value of the backlog for teams that practice Kanban or Scrum. And, it provides links to our agile microsite where people can learn in-depth how to practice agile methodologies using Jira Software.

It's deceptively simple, this topic, but extremely clear in explaining what the backlog concept is, and the value it brings both generally and to a person's specific use case.

An unhealthy conceptual topic

Now, onto an unhealthy conceptual topic. Its easier to pull out insights from work that's underperforming, in my opinion. You can learn a lot more from your mistakes than from your successes.

Let's look at the in-product topic "How are next-gen project settings different than classic?". It was the most-viewed in-product conceptual topic with the lowest helpfulness rating in June 2020. Also, it's my cross to bear because I wrote it.

This topic has maintained an average helpfulness rating of around 43% consistently for the past 5 months.

Some general information about this topic:

• The topic is 330 words long.
• It's at an 8th grade reading level.
• It takes about 1.5 minutes to read (if you understand all the words in it!)

The structure of this concept is a bit unclear, but let's say it looks something like this:

• Title, in the form of a question
• Discussion about permissions
• A tip on migrating between project styles
• Mental model explanations for next-gen Jira concepts (without actually comparing them to classic projects)

Right off the bat, we have a problem. The introductory text for this concept does little to address the question posed in the title. The structure of the topic itself is unclear and wandering.

And, worse, this topic is loaded with jargon. It assumes an abnormal amount of prior knowledge. It assumes that the reader knows (and cares about):

• Jira's two project styles
• How permissions work in Jira
• How Jira concepts work in classic projects (realistically, only Jira admins would have any familiarity with this)

It isn't immediately clear who the primary audience is. It feels like it's directed at Jira admins, because of the value statements provided ("anyone can manage their own work, their team’s work, and their working processes, without having to reach out to a Jira admin for help"). I'd love to show/hide this topic based on a user's permissions and see if it's helpful to Jira admins, specifically. But, that audience doesn't make sense in the context of where this topic appears. Help seekers in next-gen projects are likely end users, not Jira admins.

The value statements are lacking:

• "You can make updates without worrying about affecting other software projects on your Jira site". Putting my end user hat on, I assume this is true without reading this. So, there's no real value here for my primary audience (although there may be some for the Jira admin audience).
• "Anyone can manage their own work, their team’s work, and their working processes, without having to reach out to a Jira admin for help". Again, I assume this is true or I wouldn't have access to these settings pages.

So, we've failed to analyze our audience correctly and directly address their needs. This is the first thing we need to address in our rewrites.

We also need to address the jargon and relate these concepts to real life, rather than using more jargon to explain concepts.

For example, our explanation of issue types which "have their own workflows, which are unique to your project" and "you can quickly update or change the fields your team uses" means little to people who don't know what workflows, projects, and fields in Jira are or how they relate to their team's work.

What's more, these concepts don't at all deliver on the promise of the title, to explain the differences between next-gen and classic concepts.

When I rewrite this topic, I’ll structure it like this:

• Title, in the form of a question
• Definition in plain terms (next-gen projects are administered by teams/classic projects are administered by Jira admins)
• Value statement/general best practice (in next-gen, teams can experiment with agile features, and create and manage their own work/ organizations with legal or other compliance requirements can enforce best practices using classic projects)
• Mental model descriptions and differences for key concepts
  • Concept definition (reuasable component) in plain terms and link to a richer conceptual topic (what is an issue type?)
  • How this concept works in next-gen
  • How this concept works in classic

A rubric for reviewing and revising conceptual topics

After looking through some conceptual topics, I wanted to give you a rubric that you can use to assess your content's quality. If you spot unhealthy content, or if you're sparring/reviewing other writer's work before publication, hopefully the following checklist can help you feel confident in what we're delivering to our customers.

For help creating content: check out our content canvas.

A note of encouragement

Don't be afraid to experiment on rewriting concepts. If you spot a concept that's unhealthy, you're really spotting an opportunity to learn what helps our readers the most.

Get in there and try to suss out why it's not helpful. The rubric above might help you diagnose and unearth potential problems with your conceptual topics.

Give a rewrite a crack, and see if its helpfulness score improves. If it does, you probably learned something that can help your other content. If it doesn't, you can always revert your changes and try again.