- SAP Managed Tags:
Were you ever faced with a documentation situation where you felt it’s just too much information? Are you challenged with constantly having to update written content that’s complex and overwhelming? Do you want to use graphics in your software documentation but are unsure about what kind of graphics to create and when?
In this blog post, we talk all about graphics in software documentation. The best part is that you don’t need to be a graphics designer or a pro at using tools to create relevant graphics.
As user assistance developers or technical writers, we don’t create software documentation for leisurely reading. We write to solve a problem for our end users. The focus isn’t on how and what we write, but more on providing the right information at the right time with the right context. Information doesn’t mean “text”. Presenting information in a visual format always helps users to understand and process the information faster.
Graphics make a big difference to software documentation when they’re used at the right place, are simple, and informative enough. Getting the right balance between text and graphics is essential. Yes, creating graphics takes time – but so does writing content. Also, graphics are not an alternate to writing content but act as supporting material to your documentation that add a lot of value.
So, what kind of graphics should you invest in, when creating them for software documentation? To answer this question, here’s a list of graphic types:
A good candidate for using graphics is when you’re documenting a process. A process is described by a sequence of steps. Something starting from one point in your software landscape that goes through a set of steps to finally give you a particular result. It doesn’t matter who is executing the steps – it could be the customer or the system. Visually describing a process is an efficient way of communicating to your users about who does what, when and where. A graphic that describes a high-level process is valuable information for users in terms of giving them the big picture. Without a visual, it’s possible for users to skip steps.
Here’s an example of a process graphic in our documentation: Collaborating on Provisional Specifications
Another situation that deserves a graphic is when you’re describing software architecture. An example could be when you’re documenting a development infrastructure landscape where several components are involved. You create an architectural diagram to show the different components and how they come together in the landscape. You can also create a process diagram to represent the processes that use the different components in the landscape.
Take a look at an architectural diagram created for a product landscape in SAP documentation: Overview of SAP Enterprise Product Development
An infographic is like a snapshot in a single page – something that’s not possible to do with just text. If you’re writing a high-level introduction for a product, a great way to highlight important pieces of information, results, and messages, is by creating an infographic. This kind of graphic gives you the freedom and flexibility to summarize information to help your users get a holistic view and saves them time from reading pages and pages of documentation. It might sound complicated to create, but worry not, you have predefined templates available for such scenarios.
Here’s a marketing example at SAP that captures the essence of what goes into an infographic: IDC Business Value Snapshot sponsored by SAP and Syniti
A combination of processes and architectures, the third image in this topic of SAP documentation shows you a different take on an infographic. The graphic is also explained in the subsequent text in the topic.
If this blog post helped you in understanding the different types of graphics that can be created for software documentation and the importance of when to use them, do share it with a friend who might benefit from it.
In the next blog post, we talk about an interesting concept called Simplified User Graphics or SUIs. If this has piqued your interest, stay tuned!
In this blog post, we talk all about graphics in software documentation. The best part is that you don’t need to be a graphics designer or a pro at using tools to create relevant graphics.
Image Source: Adobe Stock
As user assistance developers or technical writers, we don’t create software documentation for leisurely reading. We write to solve a problem for our end users. The focus isn’t on how and what we write, but more on providing the right information at the right time with the right context. Information doesn’t mean “text”. Presenting information in a visual format always helps users to understand and process the information faster.
Graphics make a big difference to software documentation when they’re used at the right place, are simple, and informative enough. Getting the right balance between text and graphics is essential. Yes, creating graphics takes time – but so does writing content. Also, graphics are not an alternate to writing content but act as supporting material to your documentation that add a lot of value.
So, what kind of graphics should you invest in, when creating them for software documentation? To answer this question, here’s a list of graphic types:
Process Graphics
Image Source: Adobe Stock
A good candidate for using graphics is when you’re documenting a process. A process is described by a sequence of steps. Something starting from one point in your software landscape that goes through a set of steps to finally give you a particular result. It doesn’t matter who is executing the steps – it could be the customer or the system. Visually describing a process is an efficient way of communicating to your users about who does what, when and where. A graphic that describes a high-level process is valuable information for users in terms of giving them the big picture. Without a visual, it’s possible for users to skip steps.
Here’s an example of a process graphic in our documentation: Collaborating on Provisional Specifications
Architecture Graphics
Image Source: Adobe Stock
Another situation that deserves a graphic is when you’re describing software architecture. An example could be when you’re documenting a development infrastructure landscape where several components are involved. You create an architectural diagram to show the different components and how they come together in the landscape. You can also create a process diagram to represent the processes that use the different components in the landscape.
Take a look at an architectural diagram created for a product landscape in SAP documentation: Overview of SAP Enterprise Product Development
Infographics
Image Source: Adobe Stock
An infographic is like a snapshot in a single page – something that’s not possible to do with just text. If you’re writing a high-level introduction for a product, a great way to highlight important pieces of information, results, and messages, is by creating an infographic. This kind of graphic gives you the freedom and flexibility to summarize information to help your users get a holistic view and saves them time from reading pages and pages of documentation. It might sound complicated to create, but worry not, you have predefined templates available for such scenarios.
Here’s a marketing example at SAP that captures the essence of what goes into an infographic: IDC Business Value Snapshot sponsored by SAP and Syniti
A combination of processes and architectures, the third image in this topic of SAP documentation shows you a different take on an infographic. The graphic is also explained in the subsequent text in the topic.
Rules for Graphics in User Assistance
Image Source: Adobe Stock
- Consistency applies to information in any format, be it written or visual. To ensure consistency, create a style guide and define guidelines, rules, and boundaries that you can refer to at any time. Invest some time in defining guidelines that apply to creating graphics in your software documentation, and then follow the rules. If your company already has a style guide, follow it. This way you provide a seamless user experience.
- Always explain a graphic using text. As mentioned earlier, a graphic is not an alternate to text.
- Ensure that your graphic adheres to accessibility norms. For example, provide an image ALT text, use the right colors, etc.
- Always store your image source files that you create in the original language and the image you export from the source file. This way, you can use the source file to update the diagram whenever required. Also, if the text in the image needs to be translated, you can send the source file for translation.
If this blog post helped you in understanding the different types of graphics that can be created for software documentation and the importance of when to use them, do share it with a friend who might benefit from it.
In the next blog post, we talk about an interesting concept called Simplified User Graphics or SUIs. If this has piqued your interest, stay tuned!
2 Comments