Technical Writing in Software Engineering Companies: 3 Basic Documents
In software engineering organizations, clear and effective information about the engineering state of the art is fundamental to succeed.
This allows the teams know to solve their engineering problems.
A crucial part on this is the technical writing, which involves creating technical documents detailing various aspects of software development and operation.
These documents not only serve as guides and references for teams but also play a vital role in problem socialization, evaluating solution alternatives, decision-making, and continuous learning based on historical records.
This article explores the importance of technical writing in software engineering companies, focusing on 3 key documents and the crucial role a Principal Engineer must play in promoting them.
The Role of the Principal Engineer in Promoting Technical Writing
As a Principal Engineer, you are responsible not only for leading initiatives technically but also for ensuring that technical documentation is of high quality and up to date. Promoting the creation and maintenance of technical documents is essential for the long-term success of the team and the organization. Technical documents provide a framework for making informed decisions, facilitate problem-solving, and ensure that best practices are shared and followed.
These are the 3 Basic Documents every engineering organization should have!
1. Golden Path or North Star
The Golden Path is a document that defines the current state of decisions about technologies allowed, deprecated, under investigation, and rejected in a company. It's the toolset to solve engineering problems.
Structure of the document:
Each technology category of the document should contain:
Examples of technologies' categories: Programming Languages, Package Managers and Registries, Frameworks (Web, Mobile, Services), Service Communication technologies, Databases, Observability & Alerting, Other tools (Feature Flags, Experimentation, Product Analytics), Content Delivery Networks & Caching, CI/CD, etc.
Benefits of having this kind of document:
PE role on this document
The PEs should implement and ensure the process to have this document up to date (creating, edition, deprecation), including the workflows needed (from edition to widely communication).
The PEs and higher engineering roles are owners/accountables of this document.
Depending on the company and the situation of the company, this document can be used as a reference on the Technical OKRS (for example, to deprecate technologies or tools, to adopt new technologies, etc).
领英推荐
2. ADRs (Architecture Decision Records)
ADRs are records of architectural decisions that document important decisions made during software development, along with their context and rationale. They can describe the decision to start using (approve) a technology, deprecate it, a new design pattern, a new architecture approach, replace a tool or a third party, etc. It collects important technical design decisions, or solutions to use in problems that have become a pattern (repetitive ones). An ADR can be supported in an existing Technical Proposal. It should be concrete, direct, and short.
Scope: based on the company characteristics and necessities, we can have different levels of ADRs: Team/Feature ADRs, Product ADRs, company ADRs, etc.
Structure of the document:
Title, Status (approved, draft, under review), approval date, authors, approvers, Problem Statement, Problem details or Context (optional), Decision, Consequences, References, Logs (doc change logs).
Benefits of having this kind of document:
PE role on this document
Similarly as in the Golden Path / North Star, the PEs should implement and ensure the process to have this document up to date (creation, and edition), including the workflows needed (from new entries to widely communication).
The PE must forster the adoption of the different ADRs based on their scope, ensuring every team adopt it at at team/feature level, and ensuring all teams are communicated about company-level ADRs.
Depending on the company and the situation of the company, this document can be used as a reference on the Technical OKRS (for example, to deprecate things, to adopt new technologies, etc).
3. Technical Proposals
A technical proposal is a detailed document describing a solution to a specific problem (Compared to the ADR, this kind of document is focused on problems that don't need to be a repetitive problem). This document includes requirements analysis, solution design (systems design, architecture), implementation considerations, and risk assessment.
Structure of the document:
Title, Basic information (author, approvers, status, date), Definitions (glossary), Problem Statement, Problem details (optional), Requirements (optional), Decision, Alternatives, Appendix (optional).
Benefits of having this kind of document:
PE role on this document
The PE must forster the adoption of this kind of document as a Team/Feature level, ensuring every team in their scope adopt it at at team/feature level.
Conclusions
The importance of technical writing in software engineering organizations cannot be overstated. Clear and effective technical documentation is fundamental for the success of teams, enabling them to solve engineering problems efficiently. This article has explored how technical writing, through key documents such as the "Golden Path," ADRs, and Technical Proposals, plays a crucial role in problem socialization, evaluating solution alternatives, decision-making, and continuous learning based on historical records.
The Principal Engineer has a vital responsibility in promoting and maintaining high-quality and up-to-date technical documentation. These documents serve not only as guides and references for teams but also provide a framework for informed decision-making, facilitate problem-solving, and ensure best practices are shared and followed.