This guest blog post was written by Dr. David Marshall, a technical writer and a training developer since 2007. He is also the owner of Neithdos Consulting Services LLC. Dr. Marshall received his DM in Executive Leadership from Colorado Technical University in 2021.
As writers we create documentation for our customers such as:
Case Studies
Case studies are employed to demonstrate how a certain product benefits a business. The company will describe how this good or service helped them achieve their objectives as a business. Testimonials or customer reviews are a few of instances of case studies.
Proposal and Pitches
To get new business, many industries rely on proposals and pitches. To convince the stakeholder to award the project to the company, technical writers are crucial to the creation of these proposals.
Brochures
Through concise product explanations, features, and uses, brochures help users comprehend and be more drawn to a product. Key phrases are used by brochure writers to persuade readers to try the product or service.
Press Releases
Businesses need a way to formally announce new information about the company. Typically, the technical writer who works with the marketing division develops this. White papers, case studies, and other types of releases are all possible.
White Papers
Marketers use white papers to highlight a product or service's successes. These documents will be used by the author to demonstrate how the good or service was successful in resolving an issue.
However, if our end users want something that they can easily access from anywhere at any time, to answer their questions on a product or service, this is where we can deliver!
Why Online Help Documentation?
If you wonder how important it is to use the internet when it comes to finding answers, especially when it comes to products and services? This may be the answer. According to a recent survey approximately 90% of millennials use the web to find answers before calling customer service and close to 70% of company’s customers will use the organization’s website before calling or emailing. As we can see online documentation is preferred because customers can get what they want instantly without searching for the hardcopy guide that is in the drawer somewhere.
What is Online Help Documentation?
Online Help Documentation is information that companies want to share with their customers, clients, stakeholders, and partners. This helps customers understand and operate the product or perform the service by breaking down technological terms to make it easy-to-understand content. Examples of Online Help Documentation include:
- User Help Guides - Provide clear and sensible answers to common questions.
- Hardcopy and Online Product Manuals - Highlight the product's main features, general maintenance, and basic operations. A great example is the operator’s manual.
- Assembly Guidelines - Instructions on how to physically set up a product with detailed documentation.
- Software Documentation - These documents show the ins and outs of a software product, such as start guides, API documentation, how-to guides and more. The key is to make it easy to understand and of interest to non-subject matter experts.
- Knowledge Bases - A knowledge base is a source of internal documentation used by human resource departments, hiring teams, to store training material or by other parts of a company to house logos and other vector images, approved copy to help keep a company organized and its employees using best practices.
To be successful in today’s world, organizations need to create online help documentation to help answer the questions that clients have.
What are the Benefits of Online Documentation?
There are a few benefits to online documentation over printed user manuals such as:
- Online Help Documentation is available anytime, anyplace, and on any device. Customers can get help using either a laptop, iPad, or mobile phone from their favorite coffee shop without worrying about what they did with the instructions that came with the product.
- It is a great marketing tool. Keywords can be used as a search engine option (SEO) that can boost the product or service.
- Using features such as videos, code, screenshots, diagrams, charts etc. can be very appealing to the end user. Who wants to read boring text?
- Able to navigate with ease. The user can use search boxes, table of contents, breadcrumbs etc. as a simple method to get around the document.
- Improved customer experience. End users will be able to get the most out of the document if it is very easy to read and follow. This builds a long-term relationship between the organization and the customer.
- Storage. Online Help Documentation can be stored where it is easily found such as the cloud. There is no need to spend precious time finding those hard copy instructions.
How to Create an Online Help Document
Creating an awesome online help document is going to take time and preparation but with patience, the benefits are never ending: Here are some steps:
- Understand the goals and the target audience. What is the objective of the document? Who is it for?
- Write down vital questions. Anticipate any questions that may come from the readers about the product and service. This will enable the writer to gather ideas, create the document, and present the information that has significant value.
- Create an outline. This is beneficial for writers to create the best layout and structure to address the objectives.
- Compile the information. If you are familiar with the topic, no problem, this should be easy. However, for most of us, it will be necessary to do online research, talk to stakeholders, and look over existing documentation.
- Create the first draft. Get the information down on your favorite document processor. See what it looks like. Recommendations for creating a first draft include:
- Avoid writing more than necessary.
- If possible, do not use jargon.
- Use simple language.
- Keep the goal and readers in mind.
- Do forget to add documentation visuals. This is what makes the customers become very interested. Use videos, images, and graphics to highlight a point or aid the end users.
- Finalize. Time for spelling and grammar checks. Have a fresh set of eyes review the document. Present it to a subject matter expert for their input.
What Tools Can Be Used to Create an Online Help Document?
There are several software tools a technical writer can use to develop online help documents. These tools assist in writing, editing, drawing, reviewing, and rewriting. A sample list of the tools available include:
- MadCap Flare - MadCap Flare is used to streamline document creation and learning & development programs. One of the favorite topic-based authoring tools for technical writers.
- WordPress - This software is used to create technical documentation in a blog form. Blogs written on WordPress can be integrated into the company website.
- Google Docs - Google Docs is becoming a tool of choice to collaborate on documents through the mobile phone.
- Snagit - A screen capture and screen recording software that can be used for giving feedback, training, or just show others how to do a task.
- Visio - Microsoft Visio is used to create design flowcharts, architectural diagrams, software product design, circuits, etc.
- Photoshop - A very popular image editing tool that creates and edits images for web pages, banner ads, and video graphics.
- IXIASOFT - With MadCap Software’s recent acquisition of IXIASOFT know that you can certainly power technical documentation using a framework that is 100% DITA compliant.
Using a Template
It may be beneficial to use a template to create an online help document so that it can be published to the server. The two templates that will be discussed are HTML and Microsoft Word
HTML
The HTML template helps the writer create a help document that displays in the Help menu. The template helps the writer produce content that uses the same style and resources as an existing help document. To use HTML, the user must have HTML or text editor that can open and save files.
While using standardized templates like HTML and Microsoft Word can provide a solid structure for documentation, employing a product documentation software enhances this foundation by offering more dynamic templates and features specifically designed for product documentation. This type of software supports more integrated content management workflows, allowing for automatic updates across multiple documents and versions when changes are made, which is crucial for maintaining consistency in product-related communications.
Microsoft Word
The Microsoft Word template assists writers that use Word 2007 or later, to include Office 365. The template provides flexibility to create new types or add existing documentation to the server. The template can be automatically creating an HTML file that is required to publish a Microsoft word document on the Help server.
Once the documents are created, reviewed and ready to be published to the help server, take the following steps:
- Open Windows Explorer.
- Open the folder that contains the document file (HTML or word).
- Open a Second Windows Explorer window.
- Navigate to the content folder.
- Copy the file(s) that needs to be published.
- Close the Window Explorer windows.
- To verify if the documents were published. Open the help viewer and search for the file.
Storing Online Help Documentation
Once the Online Help Documents have been created, it is time to store them in a document portal. A document portal provides a secure centralized place where all documentation can be accessed.
The advantages of having a document portal:
- Reduces the amount of storage space.
- Simplifies backup and recovery.
- Prevents human error data loss.
- Provides security.
- Centralized location.
For example, for organizations operating in field service, implementing a field service operations training LCMS can further enhance the efficiency and accessibility of critical service information, ensuring that field technicians have instant access to the latest procedures and compliance guidelines directly from their mobile devices.
To learn more about document portals, please read the blog How to Create a Documentation Portal located on the MadCap Software Blog site.
Make the Online Help Documentation “POP”
As mentioned in the Creating an Online Help Documentation section, the way to attract the readers is to make the documentation appealing. Here are some of the ways that writers can make that documentation “pop:”
- Embedded Videos: Adding videos is one of the easiest ways to connect with the end user. In today’s modern world, it is one of the easiest ways to explain how a product works or how to use a special feature. To maximize the impact of multimedia in training materials, incorporating a product education LCMS can streamline the creation and distribution of interactive content, ensuring that educational materials are not only engaging but also structured in a way that enhances learning and retention.
- Images and Graphics: Images and graphics can provide a way to explain something without the use of words.
- Fonts and Themes: Ensure that the fonts, themes, and colors on the online documentation blends with the website. Your customers should not feel that they are using two different websites, because the designs clash with each other.
- Breathing Space: Make sure that there is space throughout the documents. This makes it easier to read and comprehend. A congested document will turn off readers.
- Keep it simple: The document should be detailed; however, it needs to be straight to the point.
- Responsive: The document should be compatible with mobile phones, tables, laptops, and desktops. This is an online document that needs to be easily accessed by anyone at any time.
Summary
Creating a great first impression is important. Online Help Documentation can be the tool to get you there. The key to producing quality online help documentation is careful planning and thinking about the customer. As the need for hard copy documentation dwindles, online help documentation will be the go-to source.
Parker, K. (2022, June 3). Benefits of Online Documentation. Technical Writing Is Easy. https://medium.com/technical-writing-is-easy/benefits-of-online-documentation-8d72f33eda6e
7 Best Steps For Writing Good Software Technical Documentation. (n.d.). Www.wearedevelopers.com. Retrieved April 13, 2023, from https://www.wearedevelopers.com/magazine/7-best-steps-for-writing-good-software-technical-documentation
Kristin Fender (n.d.). How to: Create a Help Document using a Template. Learn.microsoft.com. Retrieved April 13, 2023, from https://learn.microsoft.com/en-us/dynamicsax-2012/developer/how-to-create-a-help-document-using-a-template
How To Create An Appealing Online Documentation. (2018, November 26). Www.helpauthoringsoftware.com. https://www.helpauthoringsoftware.com/articles/how-to-create-an-appealing-online-documentation/
