Posted March 4, 2015

Recently, I have been struggling with a business project where I have uploaded data from a .csv file stored on an Amazon S3 bucket to a Data Warehouse from another software application using a worksheet in which I must write SQL language using a schema.

Does that sound confusing? If you are a developer, you would say, " Piece of cake; I can do that with my eyes closed. "

However, as a technical writer, you are thinking, " Why me?"

As technical writers, we want to do the best job writing software manuals so that customers can understand and use the software application without any issues. 

However, what happens if we run into a situation like the one I described above? Where can we go to figure out how to describe this thing that we are trying to write about? YouTube? Google? ChatGPT? 

Sometimes, the modern ways of searching do not even help.

User-friendly software manuals may be the answer, primarily if documents are written so that even non-technical users such as myself can understand.

What are Software Manuals?

Software manuals are information about the software companies want to share with their customers, clients, stakeholders, and partners.

These manuals contain detailed instructions so the customer can easily understand and operate the software by breaking it down to easy-to-understand content.

Types of Software Manuals

There are many types of software manuals that organizations provide to the end users:

1. Administrative documentation – Provides high-level guidelines, roadmaps, and product requirements for the development team and project managers working on the product.
2. Developer documentation – Developers use these instructions for building the software throughout the development process.
3. How-to-guides – How-to-guides shows the end user how to complete a task.
4. Training Manual – Training manuals provide instructions on how to complete a task, project, or job.
5. Service Manual – Service manuals provide instructions on caring for and maintaining a product.
6. Operator Manuals - Operation manuals outline the software manufacturer's roles, responsibilities, and processes.
7. Standard Operating Procedure – The Standard Operating Procedure (SOP) contains specific instructions for accomplishing a procedure.

Importance of Good Software Documentation

Calling or emailing the customer service department is not the preferred method of approximately 90% of millennials and 70% of the company's customers who need questions answered about the software they are using. 

They will use the organization's website before calling or emailing. 

As we can see software documentation is preferred because customers can get what they want instantly without searching for the hardcopy guide that is in the somewhere in the house or at work.

Good software documentation reduces the time and effort of the support team because it gives users the power to troubleshoot.

Software documents are living manuals because of technological improvements such as Artificial Intelligence, Machine Learning, Software updates, new hardware, etc.

Writers are constantly updating the documentation.

Most importantly, software documentation improves customer satisfaction and user experience.

What are the Benefits of Software Documentation?

There are a few benefits to Software documentation over printed user manuals, such as:

• Software Help Documentation is available anywhere, anytime, and on any device. Customers can get help with 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 optimization (SEO) option to 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?
• The user is able to navigate with ease. As a simple method to get around the document, the user can use search boxes, a table of contents, breadcrumbs, etc.
• It has improved customer experience. If the document is easy to read and follow, end users can get the most out of it. This builds a long-term relationship between the organization and the customer.
• Storage. There is no need to spend precious time finding hard copies because software documentation can be easily found in the cloud.

Best Practices

Creating an extraordinary Software help document will take time and preparation, but with patience, the benefits are never-ending. Here are some steps:

1. Understand the goals and the target audience. What is the objective of the document? Who is it for?
2. Write down vital questions. Anticipate any questions from the readers about the product and service. This will enable the writer to gather ideas, create the document, and significant-value information value.
3. Create an outline. This is beneficial for writers to create the best layout and structure to address the objectives.
4. Compile the information. If you are familiar with the topic, no problem; this should be easy. However, for most of us, doing Software research, talking to stakeholders, and looking over existing documentation will be necessary.
5. 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:
6. Avoid writing more than necessary.
7. If possible, do not use jargon.
8. Use simple language.
9. Keep the goal and readers in mind.
10. Do not forget to add documentation visuals. This is where customers become very interested. Use videos, images, and graphics to highlight a point or aid the end users.
11. 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 a Software Document?

A technical writer can use several software tools to develop help documents. These tools assist in writing, editing, drawing, reviewing, and rewriting. A sample list of the tools available include:

• Google Docs
• Google Docs is becoming a tool for collaborating on documents through a mobile phone.
• Snagit
• Screen capture and recording software can provide feedback, train, or show others how to perform a task.
• Visio
• Microsoft Visio creates design flowcharts, architectural diagrams, software product designs, circuits, etc.
• Photoshop
• A top-rated image editing tool that creates and edits images for web pages, banner ads, and video graphics.
• 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.
• Adobe FrameMaker
• Writers use Adobe FrameMaker to generate structured documents with a 100% DITA-compliant XML framework.
• WordPress
• Many writers use WordPress to create technical documentation in blog form. WordPress blogs can be integrated into the company website.

Using a Template

It may be beneficial to use a template to create a Software help document to publish it to the server. The two templates are HTML and Microsoft Word.

HTML

The HTML template helps the writer create a help document displayed 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 an HTML or text editor to open and save files.

Microsoft Word

The Microsoft Word template assists writers who 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 automatically create an HTML file 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:

1. Open the Windows Explorer.
2. Open the folder that contains the document file (HTML or Word).
3. Open a Second Windows Explorer window.
4. Navigate to the content folder.
5. Copy the file(s) that needs to be published.
6. Close the Window Explorer windows.
7. To verify, open the help viewer and search for the file.

Storing Software Help Documentation

Once the Software Help Documents have been created, they should be stored 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.

To learn more about document portals, please read the blog post " How to Create a Documentation Portal "on the MadCap Software Blog site.

Make the Software Help Documentation “POP”

As mentioned in the Creating a Software Help Documentation section, the way to attract readers is to make the documentation appealing. Here are some of the ways that writers can make that documentation “pop:”

1. Embedded Videos: Adding videos is one of the easiest ways to connect to the end user. It is one of the easiest ways to explain how a product works or how to use a unique feature.
2. Images and Graphics: Images and graphics can provide a way to explain something without using words.
3. Fonts and Themes: Ensure the fonts, themes, and colors on the Software document blend with the website. Your customers should not feel they are using two different websites, because they design others.
4. Breathing Space: Make sure that there is space throughout the documents. Space makes it easier to read and comprehend, while a congested document will turn off readers.
5. Please keep it simple: The document should be detailed; however, it must be straight to the point.
6. Responsive: The document should be compatible with mobile phones, tablets, laptops, and desktops. It is a Software document that needs to be easily accessible by anyone at any time.

Summary

Creating a great first impression is essential. Software Help Documentation can get you there. The key to producing quality Software help documentation is careful planning and thinking about the customer. As the need for hard copy documentation dwindles, Software help documentation will be the go-to source.