The career progression from junior to senior or principal developer often appears clear. Advancing typically involves improving coding abilities and related technical and non-technical skills. However, reaching a senior level presents a significant career divergence.
Many developers opt for the management path, which offers increased influence and career advancement. A drawback of this track is the reduced time spent coding; many engineering managers find little to no time for programming. The focused time previously dedicated to translating complex processes into elegant code is instead spent in meetings, resolving team obstacles, mediating conflicts, and handling administrative tasks. While this work is challenging and crucial, it differs significantly from hands-on development.
Another common option is the architect track. This path allows individuals to remain deeply involved with code while expanding their impact and utilizing their experience. In many organizations, the architect track provides comparable compensation and advancement opportunities to the management track, with both potentially leading to C-suite positions such as CTO.
In contrast, the architect track can appear less clearly defined. A transition to people management involves a complete shift in daily tasks, schedule, team structure, and how work output is measured. However, an architect’s role often resembles that of a senior developer, involving activities like writing code, reviewing pull requests, and discussing deployment pipelines and data structures. This raises the question: what distinguishes an architect? Specifically, how does one demonstrate readiness for an architect position?
What is an architect?
Becoming an architect involves more than just knowledge or intelligence, which are crucial for initial advancement. It also goes beyond delivering robust and well-designed systems, although that remains vital. The core distinction lies in one key area:
- Senior developers excel at deploying code to systems comprised of code.
- Architects are skilled at deploying ideas to systems comprised of people.
This might seem like a mere figure of speech, but it holds significant meaning.
To clarify, this does not simply imply that architects are effective communicators or collaborators, though these qualities are important. It is also not a euphemism for the importance of soft skills. Instead, it signifies that an architect understands effective, repeatable processes for organizing and deploying ideas, extending beyond the methods used for machines and applications. Architects recognize that a code push has limitations; critical issues demand input, collaboration, and consensus from individuals with diverse perspectives and roles.
Essentially, most engineers in most organizations cannot initiate a multi-month project, refactor a web service, or select a programming language for a new product without approval from various developers and leaders. The primary bottlenecks in the software development lifecycle are often not code-related, but rather human-centric issues such as communication, persuasion, and decision-making.
To achieve impact, architects must consistently facilitate these interactions across sprints and quarters. The challenge lies in reliably convening the appropriate individuals, at the correct time and place, to discuss relevant topics. Is there a protocol or infrastructure-as-code solution applicable to human interactions? Indeed, there is. Several tools exist for this purpose, including Confluence, Google Docs, Notion, XWiki, and BookStack. The ability to create bullet points and link documents allows for the deployment of ideas. In most organizations, the most effective approach to accomplishing tasks involves writing a document, sharing it with relevant stakeholders, and incorporating their feedback.
Many programmers, however, lack confidence in their writing abilities. Transitioning from a domain where quality is objectively evident (programming) to one where it relies on reader perception (writing) can be challenging. The following provides a concise guide with sufficient information to confidently produce effective documents, regardless of background. Formal English education, advanced vocabulary, or native language proficiency are not prerequisites; mastering a few techniques is all that is required.
Principles of good documents
This section outlines key principles for documentation. The following values are emphasized:
- Prioritizing jotting things down over strict structural concerns.
- Fostering a culture of documentation rather than mere compliance.
- Focusing on relevance over rigid template adherence.
- Valuing point-in-time documentation over continuous updates.
These principles intentionally echo the Agile manifesto, suggesting that while the latter items hold value, the former are more critical.
Further details on these points, including document structuring ideas, will be provided later. However, it is important to remember the first and third principles: documenting knowledge is more beneficial than getting bogged down by format. The format does not need to be consistent across documents. The focus should be on what best suits the current information, rather than adhering to past practices.
How to write a document
Even with limited technical writing experience, producing excellent documentation is achievable. A remarkably simple yet effective technique that enhances almost any document is the use of bullet points.
Bullet points are highly effective. They encourage a focus on completeness and structure, rather than on sentence flow or stylistic elements. Readers of technical documents typically seek information rapidly; a key measure of good documentation is how quickly readers can extract what they need and cease reading. If information is found within ten seconds, it indicates success. Given their information density and ease of skimming, bullet points are ideal for this purpose.
The preceding two paragraphs can be summarized using bullet points:
- Bullet points are beneficial for technical writing
- They aid in focusing on completeness and structure.
- They require less advanced writing skill.
- They make documents easier to skim.
This format conveys nearly all the same information using only a quarter of the space, and it was simpler to compose. Consequently, bullet points are invaluable for architects.
The second most valuable technique is using headers. Unless the information is extremely concise and can be conveyed with minimal bullet points, it is advisable to divide it into sections with clear, descriptive titles.
For instance, many documents begin with a ‘Context’ section. This section aims to offer background information and relevant links concerning the topic’s history, business domain, or existing constraints. While the author may be familiar with this information from daily work, other readers will benefit from the reminder. Furthermore, revisiting the document later will also prove helpful.
Naturally, individuals with a thorough understanding of the subject can easily skim or bypass the Context section. This highlights the utility of headers: they facilitate quick navigation, allowing readers to locate specific information and disregard irrelevant portions. For documents with numerous headers, a linked table of contents can further enhance usability.
If initial header choices are unclear, one approach is to first list bullet points in any order. Subsequently, these points can be organized into logical groups and assigned appropriate labels. This process mirrors programming practices, where an initial 200-line method might be written, then refactored into smaller steps and functions once functional.
The primary goal is to avoid presenting a dense block of text. Individuals whose attention is most crucial for a document often have the most limited time. A lengthy, essay-style document is unlikely to be fully read. Conversely, a well-structured set of bullet points allows busy readers to quickly scan, extract necessary information, and respond efficiently.
What to do with your document
After compiling all essential information, it is advisable to perform a sanity check. Share the document with a close colleague and request feedback on any unclear or incorrect aspects. This feedback can then be used to refine, reorganize, or rephrase the content.
It is important to recognize that most documents function more like single-use scripts than continuously updated applications. Once a document has served its purpose, it is unlikely to be updated again. An architect might produce numerous documents annually, making it impractical to maintain every single one.
This has two key implications. Firstly, each document should be sufficiently robust to remain useful even as it becomes outdated. Investing extra effort upfront allows for its utility to persist without constant maintenance. Secondly, it should be simple to ascertain the document’s original creation date and to locate other documents from the same period. Point-in-time documentation is significantly more valuable when its age is readily apparent.
The suggested approach to organization might seem unconventional. Typically, documents are categorized by topic, with separate folders for different features. However, this often results in numerous folders that appear equally important but vary greatly in value. Some contain recent, highly relevant documents, while others lack documentation from recent years, or present a confusing mix of new and old content, sometimes contradictory, without a clear chronological order.
Instead, most documents are organized chronologically: by year and then by sprint, which clearly displays the timeline. For instance, within a tool like Confluence, a “space” (or “workspace,” “wiki,” “book” in other tools) is created for each team or product, providing a high-level logical separation. Within each space, the folder structure might appear as follows:
- Overview
- Architecture
- 2025
- Jan 1 Sprint
- Proposal: SSO login
- APP-132 Research on user sessions
- Jan 15 Sprint
- APP-135 Allow SSO login for configured clients
- Feb 2 Sprint
- Problems with SSO login and user roles
- Dev forecast: escalating role-permission complexity
- Jan 1 Sprint
It is important to note that continuous maintenance is appropriate for a limited number of high-level documents. For general product inquiries, an up-to-date landing page or architecture diagram is beneficial. However, most documents have a finite lifespan, gradually diminishing in relevance over time.
A common question might be, “Isn’t this counter-intuitive? Users typically search for documents related to a specific project or feature, not a particular date.” The response to this is, “A search function addresses that need.” Organizing documents by topic is akin to categorizing jelly beans: where consensus on the ‘correct’ method is rare. This leads to wasted time both when filing new documents and when searching for existing ones, as users might browse incorrect folders. It parallels organizing CSS properties logically instead of alphabetically: while placing left and top together might feel intuitive, it offers no practical advantage. For CSS, alphabetical order is quicker, simpler, and consistently effective. Chronological order offers similar benefits for documents.
Furthermore, searching is generally the most effective method. While browsing can help discover existing documents, finding specific information can be difficult if relevant documents have titles that do not immediately appear pertinent. Searching, conversely, is rapid and retrieves all matching results. A chronological organizational system effectively encourages users to search, which is often the most efficient approach. Clicking a search result then provides immediate context regarding its creation date and concurrent events.
After a document has been peer-reviewed and published, the final step involves sharing its link. If it supersedes or expands upon another document, update the older document with the new link. If it relates to an issue-tracking ticket, add the link there as well. Finally, distribute it to individuals whose feedback, approval, or consensus is required.
Appendix: High-impact document types
The architecture overview
Purpose: To quickly familiarize individuals with a system’s structure and design.
Audience: All system stakeholders, including managers, developers, operations engineers, and product owners.
When to write one: Prior to building a new system or reorganizing an existing one. Also beneficial when an existing system is challenging to comprehend.
Content: Outlines the primary components of a system (e.g., databases, applications, cloud services, load balancers) and their intercommunication. It may also detail internal components like data models and classes, but excessive detail should be avoided.
Structure: Can take the form of a diagram with symbols (cylinders, boxes, arrows), a multi-page document with sections, or a nested list of bullet points. Common formats include arc42 and C4.
How it orchestrates ideas: A current, or even slightly outdated, architecture overview assists contributors in developing a mental model of a system, enabling them to build upon, troubleshoot, and analyze it. It also helps leaders and operations engineers understand delivery, cost, and interactions with existing systems, which is crucial for initial approval.
Tips: Prioritizing the recording of information over structural perfection is key. Avoid undue concern about strict formats or symbol usage (unless desired). An imperfect, existing architecture document is more valuable than a perfectly conceived but unwritten one.
The dev design
Purpose: To gather feedback on planned code and identify unknowns or complexities before writing potentially discarded code.
Audience: Team developers and future developers seeking to understand system evolution.
When to write one: Before commencing any non-trivial coding task. Also applicable if a seemingly trivial task becomes unexpectedly complex.
Content: The level of detail is flexible. Avoid obvious or mundane specifics, but provide enough information for other developers to identify incorrect assumptions and suggest existing logic or patterns that might be unknown.
Structure: A sequence of planned steps. For example, detailing modifications to Class A, creation of Class B for specific data, or a database migration. Sections for ‘Open Questions’ (items needing resolution before starting) or ‘Alternative Approaches’ (different implementations for team input) can also be included.
How it orchestrates ideas: Development designs facilitate knowledge sharing among developers and help maintain a system’s core patterns and abstractions. They also establish a permanent record of a system’s development. For teams not utilizing pair or mob programming, dev designs offer similar benefits while aiding future contributors in learning the system.
Tips: It may seem counterintuitive, but increased documentation often leads to less code writing. Documentation helps prevent misunderstandings, incorrect assumptions, and design errors that result in extensive pull request cycles and rewrites. It can also prevent significant time investment in exploratory coding that yields no productive outcome.
The project proposal
Purpose: To convey a project’s value and cost, facilitating resource allocation.
Audience: Leaders and product owners.
When to write one: Ahead of planning meetings, or when identifying opportunities to significantly enhance or expand company products and systems.
Content: Provides a concise overview for leaders to assess project priority. It addresses questions such as importance, affected users, and estimated duration.
Structure: Typically includes clearly labeled sections like Context, Problem to be Solved, Proposed Solution, User Impact, and Estimated Engineering Effort.
How it orchestrates ideas: Project proposals are instrumental in initiating large, impactful, multi-month initiatives and defining team roadmaps.
Tips: Craft proposals that are easily approved by ensuring clarity for both technical and non-technical stakeholders. Recognize that others may not be constantly aware of the project, so provide more context than initially seems necessary. Prior research, such as data analysis for user impact, informal inquiries about problem severity, or reviewing similar projects by other teams, is often beneficial.
The developer forecast
Purpose: To highlight potential negative outcomes, particularly those foreseeable due to specific experience, and propose mitigation strategies.
Audience: Business decision stakeholders.
When to write one: When a decision appears risky or likely to lead to disappointment from an engineering perspective.
Content: Begin by summarizing the decision’s rationale and the objectives of the decision-makers. Detail the factors suggesting probable negative outcomes and describe these outcomes. Subsequently, propose mitigation methods, even if the core decision remains unchanged.
Structure: A structured document with sections such as Decision, Motivations, Issues, Likely Outcomes, and Solutions.
How it orchestrates ideas: A developer forecast enables the sharing of professional insights and encourages consideration of a plan’s potential drawbacks. It also prepares the organization for swift and effective responses to issues, rather than repeatedly addressing symptoms. Should a plan begin to falter, the forecast can serve as a guiding reference, illustrating the divergence between expectations and reality.
Tips: Maintain a neutral tone to avoid appearing overly pessimistic. Explore various possibilities and focus on identifying potential problems and suggesting solutions, rather than attempting to reverse the entire decision.
The technology menu
Purpose: To streamline technology selection for new application development.
Audience: A development team or organization.
When to write one: During project planning when there are varying opinions on technology choices.
Content: For specific technology categories (e.g., programming languages, runtimes, frameworks, platforms), highlight preferred options. Compare their strengths, considering organizational familiarity (development, deployment, maintenance), ease of hiring skilled developers, open-source ecosystem health, documentation quality, speed of initial application development, promotion of recognizable standards and patterns, and performance requirements. After assessing technical and non-technical advantages and disadvantages, provide recommendations for specific use cases, such as defaults for web services, serverless functions, or internal prototypes.
Structure: Typically a comparison chart followed by clear recommendations for various scenarios.
How it orchestrates ideas: A technology menu fosters consensus on development practices, enabling developers to rapidly initiate projects without lengthy debates over technology choices. It can also prompt reevaluation of established company defaults that persist due to tradition rather than current suitability or popularity.
Tips: Avoid promoting personal preferences. If creating the menu, solicit feedback from developers experienced with diverse technologies. Prioritize team alignment over selecting the objectively ‘best’ technology, giving equal weight to colleagues’ opinions.
The problem statement
Purpose: To achieve rapid consensus on resolving or mitigating a problem.
Audience: Project stakeholders.
When to write one: Upon encountering a problem without an obvious solution, requiring a clear organizational decision.
Content: Articulate the problem simply. If there is a clear business impact, describe or estimate its scope and severity. If the problem involves conflicting constraints, explicitly state them and their contradictions. Then, present several potential paths forward, summarizing the advantages and disadvantages of each.
Structure: Sections typically include Context, Problem, Impact, Constraints, and Possible Solutions.
How it orchestrates ideas: A well-crafted problem statement enables anyone, regardless of role, to grasp the problem’s nature and significance, and to contribute to the preferred solution. It also creates a permanent record of the discussion, useful for future reference, as larger problems tend to resurface or be re-debated.
Tips: Always include the ‘Possible Solutions’ section, even if initial ideas are not ideal. While engineers identify problems, architects are responsible for finding solutions. Presenting even less-than-perfect ideas can often prompt others to suggest better alternatives.
The postmortem
Purpose: To prevent the recurrence of catastrophic problems.
Audience: Anyone interested in a recent outage, failure, or high-priority bug.
When to write one: When a technological issue has an unusually significant impact. While most bugs do not require a postmortem, a major business disruption—such as an on-call developer being paged or customer complaints—warrants further investigation.
Content: Describe the apparent problem and its discovery in a blameless manner. Include links to relevant discussions, pull requests, and issue-tracking tickets. Detail who was affected, the resolution time, and interim mitigation efforts. Conclude by explaining the root causes and recommending preventative measures.
Structure: Sections typically include Context, Problem, Impact, Timeline, Root Causes, and Recommended Process Changes.
How it orchestrates ideas: Postmortems enable organizations to transition from anxiety about recurrence to confidence in prevention. When properly conducted, they also foster a culture that moves beyond individual blame towards collective competence and automated safeguards.
Tips: Postmortems provide an opportunity for accountability but should not be self-punishing. Everyone experiences challenges and makes errors. An organization’s goal is to build resilience beyond individual capabilities. Acknowledge personal contributions, but maintain focus on collective organizational improvement.
