We constantly hear that AI will free us up to work on more complex, strategic tasks. One of those tasks is building a landing page for docs. Why is this task difficult? Landing pages require familiarity with the entire doc set, not just one part of it. You have to make decisions about message priority and information hierarchy. You'll need to identify the product story and main features. Most significantly, you'll need familiarity with visual style guides, including approved colors, styles, graphic assets, and tools. In this tutorial, I'll try to break down some strategies and techniques for approaching landing pages. We'll use AI, but not with quick one-and-done prompts.
We frequently hear about AI freeing up bandwidth so we can focus on more complex, strategic tasks. For me, one of those tasks has been to work on a landing page for one of our products. It's something I've been meaning to get to for months. I'm not sure why I don't naturally gravitate toward designing landing pages. If you already have comprehensive documentation, creating the landing page should be simple: gather section overviews and arrange them logically in an appealing layout. Still, landing pages can be challenging, not just in designing the content and flow, but in tackling the visual and graphical elements of the page. This post includes my rambling thoughts on landing pages and why they're challenging for technical writers.
As Lavacon wrapped up last week, I've seen a few posts from attendees sharing their thoughts, including Alan Porter's Am I the AI Luddite? and Fabrizio Benedetti's How I'm using AI as a technical writer. Alan's post echoed some other sentiments I've heard from others in the industry expressing ambivalence about using AI. In fact, many of my colleagues share this ambivalence, unsure which scenarios warrant AI's use or whether it truly helps. Having been an AI proponent for more than a year now, I remain as convinced as ever about AI's usefulness in tech comm. But let me concede a few things.
Although this post by Michael Lynch titled Why I Quit Google to Work for Myself was published in 2018, it trended on Hacker News last week. It caught my attention because I recently underwent a similar promotion process, though with a positive outcome. Lynch, an engineer, highlights a couple of points relevant to technical writers: writing documentation doesn't support an engineer's demonstration of technical complexity, and the projects you work on might matter more than the quality of your output.
Janette Sadik-Khan served as the Transportation Commissioner in New York City under Mayor Michael Bloomberg from 2007 to 2013. During this time, she undertook one of the largest attempts to incorporate pedestrian- and bicyclist-centric changes to the city's roads and transportation system, rather than maintaining a car-dominant approach. Her book, Streetfight: Handbook for an Urban Revolution, authored by both Sadik-Khan and Seth Solomonow, recounts their strategies, attempts, and outcomes across many different projects and initiatives.
In this prompt engineering series, I've often focused on a specific technique one at a time, but in this tutorial, I'll show how multiple techniques can work together successfully. Techniques such as the following: the interview and transcript as a way to gather information, proceeding through chain of thought reasoning steps, switching between editorial and writer hats, and more.
Mark Wentowski has a six-week course on 'Mastering API documentation' that blends theory and practice, includes tools and workflows, hands-on assignments, projects, and more. You can learn more about it here: Mastering API documentation.
The University of Strasbourg, in collaboration with Louisiana Tech University, is holding a Symposium on Usability and Design in France April 24-25, 2025. The focus is on 'Addressing Access and Accessibility Through Usability and Design: Ideas and Approaches for Web Communication, Technical Communication and Localization.'
Some people dream of reaching inbox zero; I have a similar dream for doc bugs: I want to get my doc bug count to zero, or close to it. To try to achieve this, I've started focusing my energy on analyzing why some doc bugs aren't actionable.
The following is a guest post by David Kowalsky exploring some productivity and time management topics based on his reading and experiences with Oliver Burkeman's Four Thousand Weeks. The book encourages you to escape the efficiency trap and focus on what really matters in your limited time.
NotebookLM can automatically generate podcasts about any content you provide. In exploring these podcasts this week, I think they might complete a piece that was missing from the GenAI picture with tech comm: these podcasts can help you understand and learn the content you're working on, even when other AI techniques might shortcut that learning.
This podcast explores GenAI in technical documentation scenarios, highlighting the AI features and capabilities provided in Document360. I talk with Saravana Kumar, CEO of Kovai.co, which makes Document360, about how AI is changing search functionality and reducing support costs in knowledge bases. We discuss practical applications of AI for technical writers, including automated tagging, SEO optimization, glossary creation, and more. Saravana shares about AI agent workflows, conversational search experiences, automating screenshot captures, and much more.
In this article, I provide a strategy for one of the most challenging topics in prompt engineering with docs: using AI to help with code samples. At the extreme end, this could mean using AI to generate code samples from documentation; at the other end, it could mean describing code that’s already been written. My approach is more of a hybrid between the two. After describing a typical scenario, I explore the difference between test code and application code and why engineers are reluctant to provide code samples in documentation.
The following is a Q&A post with Paul Maass of Zoomin about Unified Knowledge. Paul says Unified Knowledge integrates diverse content sources to improve AI-powered service interfaces and customer support. He explains the challenges of content management, the role of AI in technical documentation, and gives insights into preparing for knowledge systems driven by AI.
After publishing a day in the life guest post, I've been thinking about what a day in my life might look like. The last time I wrote a post like this must have been a decade ago. But my brain has been thinking about these day-in-the-life details for some reason so I decided to jot some notes down about my day. In this post, I note the main activities of two days of my week (a Wednesday and a Friday). I then follow this up with a detailed analysis of how I spend my time, and why it's so challenging to get AI to accelerate doc work. In looking over my day, it's constantly fragmented with microtasks and unnecessary overhead, rather than an immersive focus on deep work.