The portfolio is important for a freelancer, but case studies show problem-solving abilities, processes, and solutions adopted.

Table of Contents

1. Case study n°1: documenting cybersecurity products
2. Case study n°2: documenting software and processes for a big retail company

Case Study n°1: documenting cybersecurity products

Overview of the client and of the initial situation they had

4Securitas is a firm that develops two different products: one makes an overview of the exposure to the Internet of a company’s infrastructure. The other makes the actual cyber defense against attacks.

In the beginning, the documentation was a task of the Support Team and they mainly documented internal troubleshooting and some procedures for customers, but not in a structured way.

They wanted a person to be the actual owner of the documentation with the following goals in mind:

• Reduce the work carried out by the Support Team. In particular, as the documentation was not a company’s process, sometimes the Support Team worked overnight to create release notes on time with the software release. Among other reasons, this was also due to the fact that the firm manages documentation for external stakeholders in three languages: English (the main one), Italian, and Turkish.
• Create structured documentation, both for internal and external stakeholders.

The action plan

In such a situation, the things to do were:

• Start understanding and testing the products.
• Define the audience for the products.
• Implementing standard writing procedures.
• Create new and standardized processes.

When documenting a product, the first step is always to test the product itself because:

• Creating the documentation means representing a process step-by-step, and this can be done if the technical writer does the actual steps. While doing the steps, the technical writer starts drafting the documentation.
• While drafting the documentation, the technical writer understands the difficulty needed to complete the various tasks. This is helpful to define the audience to refer to the documentation.

For the products developed by this firm, I found two main audiences:

• Middle system administrators. This is the audience referred to as the customers: the software is on-premises and the management has to be done by IT experts.
• Middle engineers. This is the audience referred to as the internal stakeholders: everyone, even new hires, has to understand the internal documentation and how to use it.

As the current documentation was created without a structure, I implemented:

• Objectives for each category of target audience.
• Standard writing guidelines to ensure consistency.

Finally, documenting a product and creating operating procedures is a company’s process exactly as the others. So, the plan here was to define a process to be triggered with the right timing to:

• Test new features before a release is deployed.
• Write the documentation at the right time before the developers deploy the release.
• Validation of the documentation written in English as a primary language. After validation, I translated it into the other two supported languages.

The difficulties

The difficulties were mainly connected to implementing a process to make documentation on time, before the release. It took some weeks of strict collaboration with the product team, the developers, and the project manager. In the end, we implemented the following:

• Apart from urgencies, new features and bugs to be fixed are scheduled 3 weeks in advance.
• I’m triggered when the issues are open in the monitoring software so that I can start creating a draft of the release notes.
• Developers have 2 weeks of development. After that, the QA testing phase starts. When the QA testing phase starts, I start my tests and the documentation.
• When the tests and the documentation are completed (1 week), the documentation is validated by someone from the product or the development team.
• After the documentation is validated (some hours), the software is deployed.

The results

Structuring processes and developing documentation lead to the following results:

• A structured release process, granting release notes on time with no overnight work.
• Decrease of 17% of support tickets. Mainly the ones regarding issues that could be resolved with structured documentation.
• Faster troubleshooting due to structured internal documentation led to a decrease of 13% in ticket answers and a 21% decrease in engagements with developers, asking for clarifications.

Ongoing work

As the collaboration is still ongoing, I’m working on:

• Structuring a BOT on the Support portal. The goal is to educate new customers to first read the documentation when they experience an issue, instead of immediately opening a Support Ticket. This will lead to a further decrease in the job carried out by the Support Team.
• The developers are restructuring the software, from on-premises to Saas. This means I’m maintaining the documentation for the current on-premises solution and structuring the documentation for the SaaS solution that is being developed.

Case Study n°2: documenting software and processes for a big retail company

Overview of the client and of the initial situation they had

DeAgostini is an Italian big company, historically working in the retail market.

Before reaching out to me, they spent the previous 5 years digitalizing the company and the business, moving to e-commerce, but still maintaining a percentage of their business in retail.

Since years have passed since the digital transformation of the company started, they contacted me with the following goals in mind:

• Documenting proprietary software.
• Documenting the usage of software for employees.
• Implementing and documenting processes.
• Extend the documentation to the whole company (creating a company handbook or similar).

The action plan

In the beginning, they were thinking more of getting guidelines and best practices so that they could develop the documentation on their own.

I immediately suggested that this would be a vast job to do, because they had a lot to document.

So, here’s my action plan to help them:

• I asked them to define the most urgent tasks and software to document and create a list, with priorities.
• I started testing the software and tools they use in order of urgency. We made calls when I needed help or explanations.

For each product and tool, I defined:

• The audience. Often I documented software and tools for final users (how employees can use the software) and for developers (API references, and code documentation).
• The process. Documentation on my side, testing, and validation on the client side.
• The writing style. I used my own technical article guidelines.

The difficulties

As the collaboration is still ongoing, the difficulties are related to the fact that a tool or software can have different audiences.

So, I’m working on differentiating the documentation for different audiences.

The results

We have been collaborating for a few months, and the collaboration is still ongoing. The expected results are:

• Decreased time on calls and 1-to-1s when new employees are hired, facilitating the onboarding phase and the work of senior employees.
• Decreased time in decision-making, due to the standardization of internal ticket creation.
• Decreased time in the future code development, due to code documentation.
• Less meetings, due to the standardization of lean processes.