Our new help center for editors (and how we built it using Contentful)
If you’re like many companies, odds are you’re looking for a way to create a help center or knowledge base for your customers. The problem is, many of the options on the market are not very easy to get started with: they lack flexibility and often don’t integrate well with other content systems your organization may be using.
Luckily, with Contentful, you don’t have to worry about any of that. In fact, our customers often use Contentful to build their knowledge base or support portal — sometimes as their first project. For our own product, our developer audience is well-served by our developer documentation, but we didn’t have a dedicated space for another important group of users to get help: the content creators, editors, and administrators who work with Contentful on a daily basis. This is why we decided to create a knowledge base of our own, to help serve our non-developer audience.
We had a few requirements for this project:
It had to be easy to use for people unfamiliar with Contentful.
The workflow should be simple enough that anyone within the company could contribute articles.
We needed to ship within three months, with a team of only three people, two of whom were new to the company and not so familiar with the product.
Clearly, we had our work cut out for us.
Start with the end goal and build backward to the content model
We approached this project using the same best practices we recommend to others: starting with our end goal and working from there. We knew that we wanted to include three kinds of content and two types of assets. The content we chose were knowledge base articles, topic-based articles, and tutorials. For assets, we knew we’d need screenshots, and we also decided to incorporate videos from our training courses to further build awareness of all our resources for editors.
Once we settled on our audience, it was time to create our content model. After doing some research, we had to decide how to model the types of content we’d have in our help center. Some of the concepts required in order to be successful with Contentful, such as content modeling, are quite complex — which meant we’d need tutorials. But how would structuring them differ from, say, knowledge base articles?
For questions users might have as they go about their daily tasks, we needed something that could be easily referenced: someone could get stuck, find the answer quickly in our help center, and then return to work. We settled on short articles for this use case. Then we thought about another content type that’s commonly found in help centers, but not as easily defined: reference materials, such as a glossary of commonly used Contentful terms and FAQs. We decided to make these our final content type.
We intentionally kept the first iteration of our content model general, so that we could modify it as we went along, thereby letting it grow with the project.
Help center design should provide users with clear trail markers
In conjunction with our discussions on the content model, we had to think about the design of the help center. We thought about how we wanted our audience to interact with the help center. What would create the best experience for them?
We settled on a sidebar navigation, to help orient users when looking for help. That way, they can always find their way back if they end up lost in the weeds on a particular topic. To keep things from becoming confusing when navigating to a particular topic, we added highlights for the current page, so users can always find where they are in the table of contents on the side. For longer articles, there is a “Related articles” section that appears at the end, showing all the articles on a particular topic in the help center.
Tap into in-house domain knowledge when testing your concept
With the basic content model and design in place, we worked with the developer members of our team to set up a proof of concept for the help center. We tested out the design, and then added some dummy content to see if things worked as expected. We tested everything in the editorial experience: How easy was it to add articles? How complicated was it to figure out the index? What about embedding assets and videos?
As the content creator on the team, I had a unique perspective on the editorial process. A lot of things that make sense when creating content models from the developer side don’t always make sense from the editor perspective. What I liked best about the project was being able to have influence from the beginning. So often we end up working with tools that were designed for other purposes, and have to retrofit them to fit the editorial process. With Contentful and my team, I was able to have a say from the beginning. I explained how the processes should work, and my team and I worked together to figure out how to balance our editorial needs with both our technical and time limitations, along with what we could reasonably expect from the design.
I wanted to focus on things that would improve my own work: namely, content reuse and being able to define templates that would help prevent any unapproved or unedited content from being published without my knowledge. I loved being able to set up content types and workflows that were specific to my wants and needs. I loved being able to contribute to how the end product would look. I love, love, love that I can make changes and publish whenever I want without having to file tickets with developers. I love that references make my content reusable — I can update screenshots of UI changes and instruction steps without having to worry that I missed something buried deep in our archive. Most of all, I love how it makes it easy for people to both contribute to our help center, and work with me for a review, ensuring our content is up to the standards expected by our customers.
When you think you’re done, iterate
This is, in a nutshell, essentially how we built our help center. We thought about the types of content, created an initial model in conjunction with an initial design, and then continually edited and tweaked the two in tandem as our project grew. For example, we found that some of our initial entry fields were too restrictive — and that these restrictions created a loop for publishing certain entries if they weren’t added to another content type. We added new content types to our content model, such as code snippets and FAQ entries, as we received feedback from other contributors.
As I created processes and walked contributors through them, we relaxed some of the permission restrictions we had added to specific roles. Above all, we learned a lot about processes and the need for a good content modeling foundation from this project, all of which will be applied to future feature releases in order to better support you, our users. We’re looking forward to it—in the meantime, we hope the first iteration of our help center will serve you well early and often as you dive deeper into Contentful!
