Hi Makers & Breakers!
I hope your Monday is starting off strong. If you’re sitting with coffee in hand, let’s set the stage for the week. I’ve been thinking about the often-overlooked craft of documentation and how, with the right tools, it’s moving from a dreaded task to a core part of building and iterating. Generative AI is making documentation a creative process, letting us jump from a blank page to tangible diagrams with less friction.
This week’s edition brings two thought-provoking articles to our table. Tog’s Paradox explores how simplifying tasks often leads to more complex user demands—challenging the way we define product requirements. Software Explosion dives into AI-powered development, where falling costs and greater accessibility are driving a massive wave of software demand. Together with my piece on documentation, these articles create a theme around evolving complexity, rapid iteration, and the importance of staying adaptable.
So, grab your coffee, let’s get into it.
Documentation Doesn’t Have to Be a Grind
TL;DR:
Documentation doesn’t have to be a grind. With the right tools and a bit of generative AI magic, visualizing complex ideas can become the most engaging part of the process. Here’s a look at how new tools are helping me skip past the blank page, build a structure quickly, and focus on what really matters: conveying clarity.
Documentation is rarely the first thing people look forward to. It’s work that can feel laborious, yet it’s essential for anyone who needs to explain complex ideas, whether it’s outlining internal systems or creating client-facing proposals. Personally, documentation is my tool for capturing everything from high-level architecture to detailed workflows. But here’s the thing: it doesn’t have to be tedious. Documentation can become a dynamic, visual tool that makes complex information easier to understand.
Some of us are visual thinkers, and a well-structured diagram speaks volumes for us. But there’s a catch: traditional documentation tools can be a headache, with endless mouse clicks and design effort just to create a flowchart that looks halfway decent. Generative AI, though, is changing the game, offering new ways to start with a clear structure instead of a blank page and making documentation a far more engaging part of the process.
The Evolution of Visualization Tools
Until recently, creating visual diagrams for documentation was a repetitive and often frustrating process. Scripting languages offered some relief, allowing us to describe a diagram’s structure and have it rendered for us, but this still required mastery of specific languages and syntax. Complex diagrams became a challenge in themselves, and updating them was often just as tedious as creating them.
Today, generative AI tools let us move past this, transforming documentation from a task of endless setup into something tangible from the start. Now, I can describe the diagram I need, and within seconds, the AI does the heavy lifting. It’s not flawless, but it’s close enough to give me a great starting point, letting me get right into refining rather than starting from zero.
Let’s dive into the tools that make this possible and how they each bring something unique to the table. Each tool has its own strengths, and using them in combination has allowed me to transform my workflow. Here’s a breakdown of the tools I rely on, along with the practical pros and cons of each.
1. ChatGPT & Claude
Best for: Technical Diagrams (Sequence Diagrams, Gantt Charts)
When I need to create a technical process or sequence diagram, ChatGPT and Claude are my go-tos. I simply describe the interactions I’m working with, and they output diagrams in Mermaid notation. This lets me quickly refine in Notion or other documentation software, giving me a polished, integrated output with minimal setup.
Pros:
Efficient Start: These tools handle the foundational structure of a diagram, allowing me to skip straight to tweaking.
Integration with Notion: The Mermaid notation is easy to import, making it a natural fit for Notion, where I can further refine or document.
You can create diagrams directly from code within Cursor.
As an alternative to Notion, consider using Mermaid.live for creating and editing Mermaid notation.
Cons:
Accuracy Limitations: The initial output is rarely perfect, requiring tweaks to align with complex systems.
Limited Scope: These tools excel at tech diagrams but are less effective for high-level visuals or more abstract concepts.
2. ExcaliDraw’s Text-to-Diagram
Best for: Brainstorming and High-Level System Architecture
ExcaliDraw’s Text-to-Diagram feature has been a revelation for broader brainstorming and system architecture. I describe the system’s primary components, and it generates a visual layout that lets me quickly refine the design. This tool solves the “blank canvas” problem, giving me a starting point to build on.
Pros:
Eliminates Blank Page Syndrome: Provides a starting visual to refine, which saves time.
Reduced Manual Effort: Less clicking and dragging, so I can focus more on refining than on setup.
Cons:
Basic Customization: Limited detailing options mean I often have to export the draft to other tools to make final adjustments.
3. Napkin.ai
Best for: Abstract Visualizations and Conceptual Diagrams
For abstract concepts, Napkin.ai stands out. It translates text into visuals that capture high-level relationships and abstract ideas. This tool has been a game-changer when I need to visualize complex workflows or relationships that don’t necessarily fit into traditional diagram structures.
Pros:
Perfect for Abstract Ideas: Great for capturing concepts and relationships in a visual format without rigid diagramming.
Presentation-Ready: Output is polished and ready for use in presentations or documents.
Cons:
Less Control Over Specifics: Better suited for generalized visuals than for details. Limited design options.
Limited Export Options: Some exports require further formatting before they’re presentation-ready.
4. Ideogram
Best for: Graphics with Integrated Text (Presentations, Document Headers)
Ideogram shines in a surprisingly specific area—creating graphics that integrate text, which turns out to be challenging in most AI tools. For presentation slides or polished documents, Ideogram’s reliable text output (with zero typos!) has saved me countless hours.
Pros:
Precision Text Integration: Text output is typo-free and visually well-integrated, ideal for polished graphics.
Flexible Use Cases: Text capabilities make it useful for headers, illustrations, and other design elements in documents.
Cons:
Limited for Technical Diagrams: Not intended for diagramming complex systems, so use it for graphic elements instead.
Additional Editing Required: Some graphics need minor adjustments in design software before they’re ready.
From Tedium to Tangible
With generative AI tools like these, documentation isn’t the drag it once was. Instead, it’s a dynamic process of building visuals that clarifies complex ideas. Each tool offers a unique strength, and when used in combination, it transforms documentation from a chore into an engaging, efficient part of my work.
These tools don’t just help me write; they help me build. Documentation becomes more than just words on a page—it’s a narrative, an explanation, and, ultimately, a way to bring my ideas to life.
Curated Reads: Complexity and the Software Boom
In this week’s curated reads, we’re diving into two themes shaping the future of software. The first article, Tog’s Paradox, reveals how simplifying tasks for users often creates new complexities, driving feature expansion and changing requirements. The second, Software Explosion, examines the surge in software demand as AI makes development faster and more accessible. Together, these pieces highlight the challenges—and opportunities—of building in a world where simplicity and complexity are two sides of the same coin.
Tog’s Paradox: Simplifying Leads to Complexity
The first curated article, Tog’s Paradox, brings up a compelling observation: as we simplify tasks for users, they tend to take on even more complex tasks. This phenomenon, which you see time and time again in software development, highlights why “feature creep” isn’t just an annoyance but an inevitable byproduct of successful product design. By reducing friction in one area, we create opportunities and inspire new demands in others, leading to an ever-expanding product scope.
Think about digital note-taking apps. Originally designed to replace simple pen-and-paper notes, apps like Evernote and Notion began with basic features—allowing users to type, organize, and search their notes. As users experienced the benefits of digital note-taking, they began asking for more advanced capabilities, like tagging, reminders, collaborative workspaces, and integrations with other tools like calendars and task managers. Each new feature added complexity, transforming these apps from simple note-takers into robust, multi-functional productivity platforms.
What started as a tool to make note-taking simpler eventually evolved into complex systems for managing entire workflows, mirroring Tog’s Paradox: as initial tasks became easier, users demanded more functionality, which in turn introduced new layers of complexity to the app.
This insight challenges us to rethink our approach to product planning. Instead of striving to capture every requirement upfront, Tog’s Paradox suggests that we accept change as an inherent part of product growth. The goal isn’t to prevent scope changes but to create a framework where evolving complexity can be managed in a way that maintains usability and focus.
Software Explosion: AI, Coding, and Endless Demand
The second article, Software Explosion, pushes us to confront a future where AI isn’t just a tool but a fundamental shift in how software is created. Philip Joubert argues that as AI-driven tools make software development faster and cheaper, we’re at the start of an explosive growth in demand. Lowering the cost of software creation means companies will soon have nearly infinite software at their fingertips, not just in engineering departments but across every team. Anyone—from designers to product managers—could build or modify software without traditional engineering support.
As engineering leaders, this raises critical questions about the future of our teams and our roles. When non-engineers are empowered to build their own tools, are we ready to step into a more strategic, advisory role? Are we prepared to oversee a portfolio where AI takes on junior-level coding tasks, while we focus on architecture, integration, and aligning tech with business goals? Joubert suggests that AI will raise the value of skilled engineers by allowing them to operate at a higher level—but it also means we’ll need to let go of some traditional engineering work.
This shift challenges us to rethink our teams’ structure, skill development, and even our hiring practices. As we navigate this explosion of software, the engineering leader’s role will be to shape an adaptive and future-focused vision that balances human expertise with the immense, ever-growing power of AI.
Closing Thoughts
Together, these pieces paint a landscape where simplifying fosters new complexities, and lowered creation barriers fuel an endless appetite for software. As we strive to build meaningful products, these articles remind us to embrace flexibility and navigate the unexpected. Whether iterating documentation, evolving user demands, or leveraging AI for speed, the key thread is adaptability. In a world of constant change, those who embrace it will thrive.
Let’s keep pushing forward.
— Luka