How to Create a Simple Knowledge Base for Technical Jargon

Language is a tricky thing and can land your business into a pitfall if not paid attention to.

Now, notice how I ended the above sentence, do you have a better phrasing than that?

I am sure you do! But if you think of the meaning, it does clearly state what I am trying to say. This is a common mistake which authors commit when they are experienced and think they can write!

We forget the most basic purpose of a language  -  Communication!!

Authors are engrossed in idea of drafting a vocabulary bomb when there is no need of it.

What is the point of complicating texts when you are losing the agreement of people on its meaning.

The more you complicate your writing with less used vocabulary, the lesser people will get the meaning behind your writing.

Remember, the goal is to provide meaning and information to the reader and not a piece of your vocabulary. The reader can get a dictionary for that!

On that note, let’s talk about how to make things more simple for your customers when you are selling a software, product or anything which involves set up and troubleshooting.

When it comes to such businesses, you can expect the knowledge base to be filled with technical jargons about the product, troubleshooting and of course, your technical writer trying to act cool with his chronic vocabulary.

This gets messy for your customers. They may not be as technically sound as your team and may want simple solutions to their problems. Sometimes, author get carried away and write about the information which is not really needed by the reader.

So, here are some tips to create a simple knowledge base when you have a lot of technical jargon for your customers:

Keep it simple and short

Keep Knowledge Base Simple and Short

A knowledge base is not supposed to be a stage for you authors to show off your writing skills. It in fact needs to be simple and to the point. The simpler the words the better.

When you are a company who already is filled with a lot jargon, which has to be thrown in a knowledge base for customers then the least you can do is keep it simple and short.

Another important point to remember is to provide only the necessary details which will actually help your customer in understanding the particular topic or perform that particular troubleshooting.

If a guy on a highway asks you the way to get to the nearest hospital then you just do that!


Because it is urgent as it involves hospital. You don’t start telling him about how there are 5 hospitals in the neighborhood and their names.

So, remember to keep your language the most understandable and if there are some technical words, which can be simplified further then do that. Here are the things to remember:

  • Keep the language simple
  • Provide only relevant details
  • Define technical words or use alternate simplified words

Prioritize documentation

Prioritize Documentatio

This is a pretty obvious point but it is as important as any other. You need to understand which documentation is important for your customers and which needs to be published first.

When you open a car or a motorcycle manual, you don’t see them talking about the details on increasing size of the sprocket on first page, right?

A lot of the car or bike owners wouldn’t even know about a sprocket. So, it is important that you understand the mind of your average customer and draft your help manuals accordingly.

Research deep enough about your product, so that you would know where customers can have problem and address the initial problems first.

Walk through the shoes of a customer, from purchasing of your product to a year performance of it. This will help you to prioritize which documentation should be published first and with time, you can gather feedback of your customers to improve those manuals.

Here’s what you need to remember:

  • Address initial problems of customers first.
  • Research your own product to predict areas of assistance.
  • Gather regular feedback from customers.

Offer visual explanations

I have a lot of friends who would not read Lord of the Rings because they think “reading is boring”.

And some of them have even a better excuse, “I have already seen the movies bro! Why should I read it when I have seen the movies”.

It does make sense right?

Well, even though I personally think that reading is a different experience but of course that cannot be implied in a business.

So, when you offer visual explanations, it does offer a better environment of learning and majority of  your customers can get a better understanding  of the technicalities of your manuals and user guides.

Take advantage of your knowledge base’s capabilities. Utilize the freedom of importing images, videos, ppts and even sound clips to offer better learning experience to your customers.

Here’s what to remember:

  • Include videos and images in explanations.
  • Keep a balance in the text and visual ratio.
  • Lead with examples.

Use context sensitive help

Context sensitive help is a key feature in helping customers understand processes and troubleshooting without interrupting the flow of customer’s reading.

When it comes to explaining technical terms, context sensitive help is the best weapon you’ve got in your arsenal. Utilizing tooltips, light boxes and popups can really tackle the pain points of your customers and offer a better assistance.

Tooltip - It can be used when the documentation is a step by step guide. Tooltips can be added to offer quick information and important notes which may or may not be required by the customer. But adding tooltips can really benefit in making customers understand small technical tips.

Lightboxes - It can offer detailed information to your customers. So, if you have a guide and it also has some internal steps to get to the final outcome, then lightboxes are perfect for it. Suppose, if a customer is installing something but in order to achieve that he/she needs to quickly add something else too. In this situation, light boxes can offer such information without breaking the flow.

Popups - When you need to provide information which is highly important in a manual then a popup can assure you that customers won’t move forward without reading it.

Final Thoughts

knowledge base is a self service system and the whole purpose of it is to offer a repository where customers can resolve their queries by themselves. This desired result highly depends on the quality of your documentation.

When you are required to offer manuals which would have technical jargon then the points mentioned above can really help you simplify the technicalities for your layman audience. Concluding, I would suggest you remember the following:

  • Keep language simple and don’t show off vocabulary.
  • Take advantage of visuals and offer better assistance.
  • Utilize context sensitive help to its fullest.
  • Keep texts short and simple.
  • Prioritize your documentation.

If you are associated with such business then I would love to hear what measures you take to simplify your knowledge base. Also, if you have any suggestions or ideas then drop them in the comment box below and I’ll join the discussion.

Share this article on

Do you want a free Knowledge Base Software?

We have the #1 Knowledge Base Software for delightful self-service help center starting at $0

About the author

Brayn is a knowledge management expert. He has been published in CustomerThink, PointVisible and Apruve. As a customer support specialist at ProProfs, Brayn has been instrumental in building a robust knowledge base and documents that help support executives keep every customer delighted. You can catch up with Brayn on Twitter and LinkedIn.


Leave a comment

Create a Knowledge Base