When dealing with complex topics like data pipelines, machine learning, or cloud systems, the real challenge is translating intricate ideas into insights that are practical and easy to grasp for the audience.

One thing that has stayed with me over my many years as a technical writer and data professional is that understanding how people process information is key.

The goal is to communicate in a way that connects with them, no matter their level of familiarity. For example, machine learning concepts should be presented in ways that resonate with both technical teams and decision-makers.

Writing effective documentation goes beyond explaining the “how”; it also shows the “why” behind solutions and helps teams see their value and potential.

A vital part of this process is breaking down information into smaller, manageable pieces—a concept known as chunking.

Structure content into clear sections, making it easier for readers to focus on one aspect at a time. This approach reduces cognitive overload and improves retention, aligning with the idea that people absorb information better in small doses.

Tools like diagrams, code examples, and concise summaries aren’t just helpful—they’re essential for guiding readers without overloading them.

Visuals also play a big role in technical writing. Data is often visual by nature, whether in charts, dashboards, or diagrams.

A well-designed diagram can explain a complex concept more effectively than paragraphs of text. The goal is always to simplify without oversimplifying, ensuring visuals add clarity without sacrificing depth.

Tone and language matter too. Writing for diverse audiences means balancing technical detail with accessibility. You should aim to simplify explanations without losing their meaning.

This can involve focusing on the purpose behind the concepts—why a model performed better or why a tool suited a specific need. Explaining the reasoning in relatable terms builds trust and keeps readers engaged.

Technical writing also evolves, much like building and refining data systems. Documentation isn’t static—it adapts as products change and audience needs become clearer.

Good technical documentation bridges gaps across teams. Clear documentation strengthens collaboration between developers, operations teams, and business stakeholders. A product that’s well-documented is easier to adopt, troubleshoot, and scale—benefiting everyone involved.

Storytelling adds another layer of connection. I’ve found that framing technical concepts as real-world case studies makes the material stick.

Instead of explaining a data engineering process in abstract terms, showing how it solved a specific problem makes the content more relatable and valuable.

At its core, technical writing is about understanding your audience. It’s not a one-size-fits-all process; it’s about anticipating questions, addressing pain points, and delivering information in a way that empowers readers.

My background in psychology has helped me appreciate how people think and learn, giving me a unique perspective on how to connect with them effectively.

Technical writing is about people. It’s about meeting them where they are, speaking their language, and giving them the knowledge they need to succeed. That’s what makes it both challenging and rewarding.

The writer:

Sooter Saalu is a data professional and technical writer with extensive experience in creating comprehensive documentation for data and DevOps products. Currently, he serves as a data-focused documentation specialist at Draft.dev, where he consults on various technical articles and documentation series.

With a unique background combining psychology and computer science, Sooter excels at simplifying complex technical concepts for diverse audiences. 

Throughout his career, Sooter has contributed to over 100 technical pieces for notable clients, including Redpanda, Dataiku, Equinix, and Expanso.

He has also made significant contributions to open-source projects like Bokeh and Bacalhau. His ability to bridge the gap between data expertise and effective communication allows him to deliver high-quality documentation that enhances user understanding and engagement.

Black Friday is almost upon us again, just in time to raise the stress levels for everyone involved. Shoppers are in a rush trying to find the deals that offer value, while retailers for their part need to achieve sales numbers in order to satisfy shareholders.

To get this right this year, these organisations will need to make the most of their investments into retail technology, while providing consumers with real value and a superior customer experience.

The origin of Black Friday dates back to the 1960s and is rooted in the description by the police of the traffic and chaos in the streets of Philadelphia as crowds came to do their Thanksgiving shopping.

Fast forward to today and Black Friday is a global phenomenon, the police have been replaced by IT teams, and the traffic is digital.

This period – and it is a period because lately the strategy has been to offer discounts over the period and reduce the resource load on one specific day – is important as a significant proportion of annual sales occur. One can say that the sales numbers help move retailers into the black so to speak – into profit. Of course, this varies by sector and strategy selected.

The continued growth in online sales locally also played a major role, with retailers focusing on e-commerce and using strategies like personalised marketing and AI-driven recommendations to capture customer interest and drive purchases.

In the end, a well-executed Black Friday means new customers, a reduction in excess stock, and a sales volume boost for the fiscal period.

For the consumer, it may mean buying goods at reduced prices and being able to save during tough times. That is if their decisions are carefully considered and not driven by impulse.

This year’s Black Friday will be an interesting one, given that the period last year was a bit of a mixed bag, with sales transactions values lower, indicating that local consumers were financially stressed.

It is likely that this year will be more of the same unless there is real value being offered to the consumer. If retailers can provide this value, however, there is an opportunity to grow their customer base.

Preparation is key

Either way, retailers will need to prepare for the period. They know that it is coming, and the planning and preparation needs to be foolproof.

This high-pressure environment is unfortunately the perfect time to drop the ball with a potential crashed website, pricing errors, running out of stock, or simply not being able to live up to the brand promise.

Retailers will need to have full visibility into where their products are stored, how the orders will be fulfilled, and even stress test third-party dependencies to ensure their readiness.

Retailers should test demand forecasting, ensure supply chain reliability and continuity, and have contingency plans in place for the unexpected.

Then, given the large volumes of data that will be created and stored over the period, cybersecurity and risk mitigation becomes a given.

As an example, fraud detection should form an integral part of their platform in order to protect both the retailer and the customer. This is crucial as losing customer data can result in liability, lost customers and reputational damage to the brand.

As such, retailers need to be agile, and must be able to monitor and adjust in real-time. Here, it is crucial that retailers have their technology partners on standby to provide support.

Staff should also be ready, trained and incentivised to deal with any type of scenario, good or bad. Black Friday is a team game, and partnerships are key to success.

Then, considering the preferences of South African shoppers, retailers will also have to find the balance between online and in-store. Thankfully, the introduction of Cyber Monday means that a focus on online sales can be planned for to a certain extent.

The customer first

I have often wondered why we don’t spend as much time thinking about how to lighten the load on the consumer.

The customer has to come first, and an improved customer experience should be a focus for all of the preparation.

There must be a way we can encourage loyalty during the year, and then use the Black Friday period as an opportunity to recognise the brand’s most loyal customers and ensure that they don’t get lost in the chaos.

Promotional strategies should be well-targeted coming back to customer first thinking. One area to keep an eye out on this year is how successful (or unsuccessful) retailers are in using AI-driven tools to recommend and drive purchasing.

There should also be flexibility in how consumers can receive our goods and perhaps incentives to influence what’s best for the retailer’s existing infrastructure and logistics.

Ultimately, the Black Friday period provides businesses with a great opportunity to make full use of the retail technology that they have at their disposal,  and to give digital platforms the needed level of attention.

This can include invoking mobile POS and clientele stations on the shop floor, or enabling self-checkout or even Just Walk Out experiences. Investing in techniques such as automated online assistants will help further reduce friction for shoppers.

Once again, retailers need to keep the customer – and customer experience – at the forefront, as failed technology initiatives will just hurt the brand.

We are all more familiar with what is needed for a superior online experience – an optimised website, performance, functionality and ease of use should all be there.

In fact, what I’m looking forward to is seeing if anyone brings something innovative and over and above the online experience this Black Friday.