Writing an introduction of a product can be overwhelming. An introduction answers why a product exists and it's primary purpose when incorporated within your environment or system.
For example,
Palo Alto Network Firewall is a product, and LogPoint (a SIEM tool) has security analytics components to extract logs from Palo Alto Network Firewall to generate meaningful insights for security analysts.
This blog walks you through the process of writing an introduction.
The introduction for product documentation can be divided into two sections:
Background
While writing background, find why a product exists and highlight its core feature(s).
For example,
In the case of Palo Alto Network Firewall, go to their official website, and read sections like "What do we do?" or "About us." Each product has a fun story, understand the scenario, and dedicate a paragraph for each scenarios.
Why the product exist?
The Palo Alto Network Firewall replaced the legacy firewalls and UTMs that could no longer defend the threats or malware with the changing security dynamics and modern attack tactics.
Next, explain why your company decided to integrate the product and the benefits customers will render from it. In our case, why Palo Alto Network Firewall is integrated in LogPoint, and what benefits customers can yield from it?
For example,
Why was Palo Alto Network Firewall integrated into LogPoint?
To extract the logs from Palo Alto Network Firewall's products and provide valuable insights related to threats or malware within the customer's network.
Benefits customers will render from the integration?
Monitor the real-time attacks, threats, and stay protected. Also, a security analyst can benefit from planning the necessary security strategies.
Stitch the paragraphs; you have a background.
General Description
General Description is the second section of the introduction. Start with the definition of a product.
Read more on how to write a definition?
Next, write an outline for product's components with a maximum of 25 words. Explain what the features enable a customer to do.
For example,
What are the components of the Palo Alto Network Firewall application?
- Normalization packages, which normalizes the logs collected from the Palo Alto Network Firewall appliances,
- Label packages, which enables a customer to find similar logs,
- Dashboard packages, which enables visualization of the detailed firewall events,
- Report packages, which generates a report with statistical information of the firewall events,
- Alert packages, which notify customers by sending an alert about a threat or malicious activities in real-time.
Stitch the paragraphs; you have a general description.
You can view the sample introduction at LogPoint Docs.
In the case of release notes, the introduction section is always added before the release details.