A lazy developer is a good developer. Creating documentation is a waste of time. So a good developer does not like documenting.
Tag: product documentation
Knowledge base is a critical part of any product documentation . It provides a library of the main information, keywords & features about the product.
Definition
According to Wikipedia, a knowledge base (KB) is a technology used to store complex structured and unstructured information used by a computer system.
In plain English, it is a condensed list of the main keywords, topics and questions that are requested by users.
Types of knowledge bases
A knowledge base is normally used for external users as e.g. customers and users.
Internal knowledge bases can be used by departments, teams or employees from sales, marketing, product management, development, QA/testing & support to collect and describe information, specific knowledge and typical procedures.
Knowledge bases can also be differentiated by the target – it can be e.g.
- product-related knowledge base, extending the product documentation
- knowledge base for an online shop focusing on the transactional steps as e.g. shipping, payment or return of orders
Why do you kneed a knowledge base?
For new and existing users and customers, they provide a structured and always available self-service help.
The support department can forward and link incoming requests and inquiries to static, well-written knowledge base entry, providing additional information and links to related content.
Such a focused entry page can be used and linked to as reference in the product documentation, providing additional background information about a specific topic.
A public, well-written and strong knowledge base entry page for a specific keyword or topic will rank in search engines and attract new visitors, and customers.
How to create a knowledge base
The following steps describe basic steps to create and maintain a knowledge base.
- Gather key stakeholder and knowledge person from different departments, especially from support, marketing, sales and product management. If possible, set up a meeting with all people involved.
- Collect content. Focus on typical issues, problems and key features. Suggestion: provide post-it notes to all involved people, write the keyword or topic on a post-it note, and let everybody present them.
Additional sources could be search queries from the website, reports from support department or the product manual. - Categorize the topics into cluster (e.g. moving related post it notes together on a wall or whiteboard).
- If not already done before or existing, choose a suitable knowledge base product and set it up.
- Create knowledge base entries for the main keywords, e.g. using the knowledge base template below. Add typical search terms to content, and links to related pages.
- Add links from external pages as e.g. product documentation, support tools or the company website.
- Update regularly: all people from step one should continue improving the content. Support department adds typical new support requests. Product management adds new features in each release. One person is appointed that regularly checks the knowledge base and e.g. removes no longer relevant content and improves unclear pages.
- Measure – use the users behavior and the search requests to learn about the content, and missing or problematic features. If the knowledge base software does not provide such a feature, a website monitoring solution as e.g. Google Analytics could be used.
Go back to step 7 with the results – add, improve and remove.
Does and doesn’t
- Be clear and consistent. Not too much words. Include images or videos only if it provides additional information.
- Structure the content using categories. Focus on relevant pages. Do not add unnecessary content.
- In the knowledge base entry, add links to features and additional information of the product documentation.
- From the product documentation, add links of keywords and terms to the related knowledge base pages.
Knowledge base entry template
… or how to write a good knowledge base page.
Remember – be precise and consistent. Do only write relevant information.
For each entry, the following parts should be present:
- Title:
- Introduction: 1-2 sentences, definition/main features
- Images, screenshots or short video
- Description
- Further reading & link to detailed/related content pages of e.g. the product documentation
Depending on the type of knowledge base, these topics and categories could be present
- Onboarding of a new user
- Main features of the product
- For the administrator user, working with user management, access rights & security.
- Reporting – use existing reports, and create custom reports.
- Payment & shipment
- How to contact support and links to self-service help sources
Knowledge base products and software
There are various solutions and products available. Providing a complete list is not possible, since new products and features are added every month.
To choose the suiting product, a short evaluation should be performed. Here are some criteria that could be taken into account:
- How is the content structured?
- Is there a search functionality – and how good is the result?
- Is it possible to create a page for each entry? Can the page be optimized for direct linking and search engines?
- How good is the online editor? Can you add additional resources easily?
- Does the tool provide reports for the users search requests, the top/poor content pages and other relevant metrics to improve the knowledge base?
- Can the portal be customized? Can you upload your logo, customize layout (e.g. CSS) and company font styles and colors? Does it provide customizable placeholders in header/footer e.g. to link to your support portal, main website, product landing page and sales team?
- If you need a advanced knowledge base, check and compare features as multi language knowledge base (e.g. translation, linking, referencing, maintaining, multi-language image and file handling), user-rated content and white-labeling / having a subdomain as e.g. help.yourdomain.com .
- Does the tool provide specific functionality to manage internationalization, translation and multilingual content?
Typically, the following categories will evolve
- Self-hosted and maintained, e.g. using a CMS like WordPress with additional plugins as https://wordpress.org/plugins/wp-knowledgebase/
This is cheap and suitable for a startup or a small company. - Integrated support suites as ZenDesk, FreshDesk or hubspot . They provide a great feature set, but can be quite expensive depending on the number of employees and users.
- Specific knowledge base products and solutions as e.g. helpjuice , proprofs knowledgebase and helpsite.com
If only a knowledge base is needed, this could be a good match.
Further reading
You can find more information about knowledge base processes and best practices on the follow pages
- https://en.wikipedia.org/wiki/Knowledge_base
- https://www.atlassian.com/itsm/knowledge-management/what-is-a-knowledge-base
- https://www.hubspot.com/knowledge-base
Final notes
Start now, if you are not sure if you need a knowledge base or not for your product. Your customers, your marketing, your sales and the support department will thank you.
Get all relevant stakeholders on board, and start with a first effort.
Schedule regular improvement sprints e.g. every month or every release. The users search queries, rated entries and support requests are very helpful to focus on the relevant topics.
What makes a perfect product documentation? Is there any exceptional documentation example? How much effort should be put into?
Product documentation is always outdated, hardly to understand and only written for the DAU or power user, and thus does not help the average user.
The fictional user
Product manual from the users perspective
Looking at the average user of a product, the typical usage pattern is: buying the product, unboxing it, starting and using the product, running into a problem and calling the support for help – of course with highest priority and requiring the solution ASAP.
The documentation, help system, manuals, technical document or operation instruction are used only by probably 30-50% of the users, depending on age, gender, background and the product itself.
In the past, the product documentation was not very “user friendly”, written with technical terms, long and hard to understand sections, screenshots and step by step instructions. It was teaching the program and application, from the creators perspective.
Looking at todays user that interacts with a new application, web page or mobile app – they only search for a help button or linked online manual in case of emergency. The product itself is expected to be simple, user-friendly and easy to grasp – even for complex tasks or features.
Reading a big book or textual folder of written pages is no longer accepted. Also big Word or PDF files with hundreds of pages are not user friendly.
Different user persona as e.g. the new user, a power user or administrator of the customers IT department need different type of documentation.
Today a multitude of application, software and apps are used together. They are running somewhere in the cloud, or are installed on-premise in the local network. Often, the products use different concepts of the user interaction and usability differs. So, the user is confronted with a set of totally different “things” to solve the tasks on hand, in a very short amount of time.
Product documentation – as seen by the producer
Todays customer is expecting regular updates of the product with change logs and release notes. The modern, agile development environment produces new product version in short frequencies – with monthly, bi-weekly and even multiple updates every day.
Keeping the documentation of a complex, advanced product up to date is very challenging. Technical writer or other experienced employees need to keep track what changed and update the manuals.
Often input and knowledge of the development, testing, sales or support teams needs to be incorporated into a well-written documentation.
For multi-language products, requiring additional translation and verification steps, the process gets more complex and delays the production of the final documentation even more.
Advanced manual incorporate screenshots, videos and other resources. Keeping them up to date with every product update is nearly impossible – especially in a multi-language application.
The manuals, onboarding resources, knowledge base and more user-product-related information can be handled by the support platforms as Zendesk or Freshdesk. They are focused on providing Q&A information, and help the customer in need. Mostly, providing product documentation is only a part of the whole support platform.
So what is the perfect product documentation?
Looking at the market, there are various product documentation products and platforms available.
This could simple as e.g. providing PDF file-based documents or even written folder.
If an online-based solution is required, a Sharepoint site or a hosted WordPress website could good enough.
For a more complex product with a bigger user base, a support platform with build-in product documentation and knowledge base could be a good fit.
A developer-centered approach as using Asciidoc-based files during the development- and QA phase is also possible.
Specific, stand-alone documentation platforms providing multi-language, versionized user manuals are on the other side of the market.
As always – there is not one perfect solution. Depending on the product, target market, the companies structure and departments a different approach is better suited.
Starting with a simple approach, targeting the customer needs and problems at hand, and improving the tooling and processes over time is often the best way to solve this problem