Twitter has grown rapidly, and change internally puts a burden on the IT team to scale support. They’ve done that with a robust knowledge base in Confluence.

Read on for advice from Twitter’s Manager of IT, Alex Stillings, and IT Support Engineer, Alex Hernandez, about how to build, organize, and improve a knowledge base that employees will actually get value out of so your IT team reduces tickets and saves valuable time and effort.

Tip #1: Do it as soon as possible

You’ve probably got a mountain of service desk tickets to work through and your team can never seem to get to the bottom of them. That’s exactly the problem Alex Stillings, Twitter’s IT Manager, needed to solve.

“How do we reduce incoming ticket numbers?”, he wondered. “If the customer portal could raise up articles that might help users and not require them to even file a ticket, that’d be awesome.” Building and organizing a knowledge base seemed an obvious lifesaver for a team drowning in tickets.

To get started, Stillings made writing and organizing their knowledge base a key deliverable for his service desk team over a quarter.  He created a mini-team – the KBase team – that met regularly to share learnings and check in on progress. They faced initial resistance from some groups that didn’t want to change their documentation, which made his team hesitate “because we didn’t want to ruffle feathers.” In the end, though, Stillings says, “my gut reaction is we should’ve done it sooner.”

Since Twitter uses Jira Service Desk and Confluence together, relevant knowledge base articles now appear when employees are browsing request types – i.e., before a ticket for the IT team is ever created. Stillings’ teammate, IT Support Engineer Alex Hernandez, agrees that the long term benefits make it worth it.

With an easy-to-follow knowledge base, we save so much time because Twitter employees can resolve issues themselves.

Tip #2: Remove barriers to content creation with templates

A good knowledge base makes it simple for your team to create articles, and easy for users to find the articles they need. “For end user support, [articles] need to be succinct and easy to follow,” Stillings says. “A technical person is going to write one and it’s going to be correct. But it will be hard to consume in many cases.”

The solution? Create templates. “Once we had a template,” Hernandez says, “it was actually wasn’t much effort at all.”

“When you use a template, all of your pages look the same,” Stillings explains. And the consistent formatting makes the articles easier to digest. They also made sure articles were written in a consistent, no-nonsense style. “Cleaning up and making sure pages are succinct is very important.”

They took advantage of page templates in Confluence, which has “troubleshooting” and “how-to” templates built in. But you can also customize those or create your own templates to match your company’s style and needs – which is exactly what Twitter did.

Here are two examples of pages from their knowledge base. The first one doesn’t use a template, while the second one uses their standard “instructions on the left, screenshots on the right” format.

Compare that with…

An example of a good knowledge base article.

Notice the difference here. Clear text instructions on the left with supporting images on the right are easy to follow, and section headers make scanning to find the information you need easy.

Tip #3: Organize your knowledge base with labels

Creating the knowledge base articles is a good start, but you still need to make sure people can find the article they need. Luckily for Twitter, Confluence and Jira Service Desk have built-in technology to help direct people to relevant articles and learn what search terms relate to which request types.

But Stillings’ team went the extra mile to direct people to the right content and keep their knowledge base organized.

Just typing “Mac” into the search field was useless because “almost everything in our knowledge base has the word Mac in it,” Stillings explains. So how does he recommend solving this problem? “You need to spend some time categorizing.”

Twitter used labels in Confluence to help guide certain search terms in Jira Service Desk to articles with particular labels in their knowledge base. See the screenshot below for how they mapped Requests to articles with specific labels. (More on that here.)

Tip #4: Improve content with customer feedback

You can plan and strategize all you want, but you never know what’s going to work until people actually start using your knowledge base

The Twitter team found this out first-hand. “At one point we were doing videos – video how-to’s,” Stillings explains. Videos sounded great, but in practice, a simple page worked better.

“In the end, when I’m hustling to show someone how to set up email on their Android device, I didn’t have time to watch the videos, I just wanted step by step instructions. You can make pages complicated and add fluff, but you should also have the standard detail,” Stillings says. “[It was] one of the examples of, ‘We went down this path and it wasn’t the right way in the end, so we course-corrected’.”

Don’t be afraid to fail and adjust.

Hernandez agrees. “I think it’s important to get the information down somewhere – regardless of how it looks,” he says. “What’s great about using Confluence is that we have the ability to change and update pages when needed.”

Tip #5: Give people one clear path to your knowledge base and IT docs

The integration between Jira Service Desk and Confluence means people will get to your knowledge base articles, but you can take it to the next level with a central page in Confluence for IT.

If done correctly, your knowledge base becomes more than just a warehouse of information for your employees,” Stillings explains. “It can also be the jumping off point for any interaction with IT.”

Twitter used to have different links for their IT Service Desk, knowledge base, general help desk, and other documentation. Now they just have one link that points people to this Confluence page:

Knowledge base tip: give people a jumping off point for documentation in Confluence.

“It helps us to look more organized,” Stillings says. “New hires come in and have a one stop shop for all their needs. If they come here to create a ticket, they may end up solving the problem themselves, whether that’s through the ticket portal, through the categories below, or through the fact that they can see when the [live] help desk is open.”

A knowledge base for your service desk is just the beginning. See what else Confluence can do for you and your IT team.

Learn more about using Confluence as a knowledge base

Twitter’s 5 tips for a successful knowledge base