Use of diagrams

Visual elements like diagrams, images, and illustrations are effective tools for making your documentation engaging and easy to understand.

They’re great for explaining complex concepts, processes, or workflows. Additionally, they break up large chunks of text and improve readability.

Using diagrams is an effective way to communicate complex ideas. They present information visually, making it easier to understand and remember compared to lengthy paragraphs.

Diagrams also illustrate relationships between concepts, helping you grasp the bigger picture. Incorporating them into your work can save time, simplify communication, and enhance documentation clarity.

In this Module, you will learn:

  • Why you need diagrams in technical documentation,
  • Tools to diagrams,
  • How to create effective diagrams, and
  • Do’s and don’ts for using images in technical documentation.

Why do you need diagrams in your documentation?

Diagrams in your documentation can enhance communication. Consider using them for the following reasons:

  • Visual clarity: People learn and understand information differently. Diagrams provide a visual representation, clarifying complex concepts and making information accessible.

  • Simplify complexity: Technical documentation often involves intricate systems. A well-crafted diagram breaks down complexity, making it easier for readers to grasp.

  • Enhance comprehension: A picture is worth a thousand words. Diagrams can replace lengthy text, showing relationships between components and improving comprehension.

  • Quick reference: Diagrams serve as quick guides for troubleshooting or processes. Users can glance at them for guidance instead of reading through paragraphs.

  • Time-saving: In the fast-paced world of technology, time matters. Diagrams help users quickly find information, reducing the time spent searching through extensive documentation.

Did you know?

Did you know that most installation manuals use images to guide users through the process instead of text? Utitlizing this method allows these manuals to be used by people who speak different languages.

Diagrams are useful for conveying messages in various technical documentation forms, such as API documentation, how-to guides, tutorials, or a simple README file. However, creating diagrams may be challenging without design skills or proper tools.

Tools you can use to create diagrams

Effective diagrams require the right tools. Numerous tools are available, but not all are equal. Here are some options:

  • Figma: Known for interface design, Figma is also great for diagrams. Its user-friendly interface and collaborative features make it ideal for technical documentation.

  • Specifically designed for graphs and diagrams, this tool supports collaboration and is free to use.

  • Lucidchart: Popular in cloud engineering, Lucidchart is free and excellent for creating architecture diagrams of complex systems.

  • Excalidraw: This tool creates sketch-like diagrams with a freehand feel, offering a natural and authentic look.

  • Microsoft Visio: If you use Microsoft Office, Visio is a powerful tool for professional-looking diagrams.

All these tools can export diagrams in various formats (SVG, PNG, JPG), making it easy to insert them into your documentation.

How to create effective diagrams

Creating understandable diagrams is crucial. If your diagram is too complex, readers may struggle to follow your message. Here are tips for effective diagram creation:

1. Keep It Simple, Yet Informative: Simplify your diagram for clarity. Each element should directly contribute to understanding the concept. For instance, in cloud engineering, architectural diagrams should present a high-level view without overwhelming details.

clear image

Figure 1. Architectural diagram displaying clear information

2. Embrace Consistency: Consistency is key. Use uniform shapes, colors, and formatting throughout. In web development, consistent symbols in user flow diagrams make it easier for developers and designers to interpret user journeys across different parts of a website.

consistent image

Figure 2. User flow diagram displaying image design consistency

3. Thoughtful Use of Labels and Annotations: Guide the reader with clear labels and annotations. In data science, well-placed annotations in process flow diagrams highlight critical steps, aiding data scientists in understanding and optimizing workflows.

data image

Figure 3. Data flow diagram displaying proper use of labels

4. Align with Audience Expectations: Tailor your diagrams to your audience. In network security, align a network topology diagram with security professionals’ expectations. Highlight security layers, emphasize attack vectors, and use familiar conventions for effective communication.

5. Utilize Visual Hierarchy: Guide the reader’s eye with visual hierarchy. In plain diagrams explaining conceptual ideas, use size, color, or placement to emphasize key elements. This enhances understanding, whether illustrating a decision-making process or showcasing relationships between concepts.

It’s not just about creating a diagram but creating one that works. Keep it simple, consistent, and aligned with your audience’s needs. Your diagrams, when simple and aligned, become powerful tools for communication in any technical domain. Embrace the visual language, and let your diagrams tell a compelling story!

Do’s and Don’ts for effective technical diagrams

As with any concept, usage rules apply. Consider the following when creating diagrams for technical documentation:

Do’s for Using Images in Technical Documentation:

  • Utilize alt text: Include descriptive alt text for images. This boosts SEO and ensures accessibility for screen reader users, enhancing inclusivity.

    The following is an example of alt text in markdown:

    1  ![alt text](/path/to/image.png)
  • Figure descriptions: Accompany images with clear figure descriptions. This helps readers, especially in scenarios like network security diagrams.

    The following is an example of a figure description in markdown:

    1  Figure [NUMBER]. [DESCRIPTION]

  • Give credit: Provide proper attribution when using images created by others. This maintains ethical standards in content creation, crucial in web development.

    The following is an example of image attribution in markdown:

    1  ![alt text](/path/to/image.png)
    2  Figure [NUMBER]. [DESCRIPTION]
    3  Image source: [SOURCE]

    Or you can give credit in the figure description:

    1  Figure [NUMBER]. [Image source] from [image author]
  • High resolution: Maintain high-quality images for clear and legible details, benefiting both technical writers and developers.

  • Unified formats: Stick to consistent image formats for a polished look. Whether you’re a technical writer or developer, using a unified format enhances professionalism and readability.

Check your knowledge:

Question 1:

As a technical writer creating diagrams, I should do the following EXCEPT:

Question 2:

Why is it important to give proper attribution when using images created by others in technical documentation?

Don’ts for Using Images in Technical Documentation:

  • Avoid overcomplicating images: Steer clear of overwhelming your audience with overly complex images. Whether you’re a developer illustrating code architecture or a technical writer creating process flow diagrams, prioritize simplicity. Avoid unnecessary details that might confuse rather than clarify.

  • Avoid unclear figure descriptions: Ensure figure descriptions are clear and concise. Technical writers and editors should provide enough information for readers to understand the image’s relevance. Ambiguous descriptions can lead to misinterpretation.

  • Avoid including personal information: Be cautious not to include personal information in diagrams or screenshots, especially when showcasing your codebase. Prevent exposing sensitive information to the public.

  • Don’t Neglect Consistency in Style: Maintain a consistent style throughout your technical diagrams. Whether you’re a developer illustrating system interactions or a technical writer creating documentation, inconsistency in style can lead to confusion. Stick to a unified design language to ensure a cohesive and professional appearance across all your visual elements.


Complete the following exercises before procedding to the next module.

Navigate to the Technical Writers Mentorship Program YouTube page and complete the following exercises:

  • Watch the Introduction to Git and Github part 1 & 2 videos.
  • Create an article on any blog of your choice explaining the steps to create a Github account.
  • Make sure to include visual representation that guides a user at each step.

You must use an annotation tool such as Annotely to create your diagrams.

Also, adhere to all the tips and measures from this documentation. After review, tag @TechnicalWriti6 on Twitter to the link to your article.

Answer the following questions.