Within SKUTOPIA, technical writing isn't just a support function—it's a cornerstone of our technical innovation. It is about conveying complex ideas and information to an audience who may not have the same level of technical knowledge as the writer, thus enabling the fundamental relationship between product and platform engineers, product managers, and product designers.
At its core, technical writing is more than just creating user manuals or API docs—it's about bridging gaps and making complex systems accessible and usable, while conveying decisions to a wide range of stakeholders.
SKUTOPIA's Engineering Structure
To understand the SKUTOPIAN approach to technical writing, understanding our engineering structure is fundamental. If you want the details, we suggest you read Engineering Levels at SKUTOPIA, and Cross-Functional Squads at SKUTOPIA.
In short, each of our product engineers—the squad members—actively works within the product trio. This is composed by the squad lead, the product manager, and the product designer; occasionally, it can include a Vertical Technical Lead, and an Engineering Manager.
Because the Product Team is a cross-functional team, this structure fosters a continuous alignment between the engineering verticals and the broad view and goals of product development. While this helps us innovate faster while remaining aligned, doing so requires maintaining a solid communication—and that's where technical writing comes to the forefront.
Technical Writing Benefits
As we mentioned before, SKUTOPIA relies on technical writing to ensure everyone remains aligned; namely, that every team member is aware of pertinent company and product goals, what objective they are working towards, and how their work contributes to that overall vision.
As a result, technical writing is more than just documenting (or commenting) code. At SKUTOPIA, and depending on someone's position and/or responsibilities, technical writing may involve: project kickoff and discovery documents, project architecture design documents, architectural decision records, code documentation, decision documentation, incident responses, project restrospectives and lessons learned, and many more.
From those, we leverage four key benefits, which we will discuss below:
We bring clarity to a complex and continuously evolving codebase.
Boost individual and team efficiency.
Support and enable state-of-the-art innovation.
Enhance overall communication.
Clarity in Complexity
We develop a highly complex, ever-evolving platform that sustains an advanced, innovative 3PL systems. To manage this complexity, our engineering teams are divided into verticals, groups, and squads to: (a) align with our Functional Domain Driving Design (fDDD), architecture, and (b) make the each squad's responsibility and scope clear.
As a result, at its most fundamental level, technical writing at SKUTOPIA is meant to reduce the complexity of our domain to enable a straightforward, low risk communication between squads, and between engineers and product managers—which includes explaining a range of related considerations, such as trade-offs, alternative paths, the choice, and the reasons (technical and business) behind it.
After all, good technical writing makes complex concepts more accessible, fostering alignment within squads and across squads, while making decision-making less error-prone.
Boosting Efficiency
For developers, the availability of well-documented code and systems mean less time spent deciphering or guessing how everything works. This has several benefits:
It simplifies onboarding, by reducing the inherent complexity and frustration associated with setting up a new development environment, and learning a new domain. This, combined with our use of Codespaces, help new engineers to become efficient, sooner.
It improves communication across teams, thus making the development of new features and the management of incidents more straightforward.
Speeds up development, reducing the time spent on troubleshooting. A clear product vision combined with an accessible, well-documented codebase boost SKUTOPIA's performance to allow us to innovate better and faster than anyone else.
Supporting Innovation
Clarity and alignment are essential qualities required to innovate. When new features, domains, or approaches are introduced, a meaningful and purposeful documentation--which is not always a synonym of extensiveness--ensures that our decision-making supporting our innovation is accessible, well-documented, and understandable in the future. In turn, this documentation allows us to understand the reasons behind past decisions and determine whether we want to continue moving in that direction, or change.Such approach helps in integrating new technology seamlessly while also empowering teams to build upon our existing systems effectively.
Enhancing Communication
Good technical writing enhances communication within and outside a squad, a group, or vertical. It provides a common language that can be understood by different stakeholders—from other engineers (which can be product or platform), to non-technical users, such as product managers and designers.
Conclusion
Technical writing may not always be in the spotlight, but its value within SKUTOPIA is undeniable. By turning complex information into clear, actionable insights, boosting efficiency, supporting innovation, enhancing communication, reducing support costs, and fostering growth, technical writing plays a crucial role in the success of our engineering teams.
