Esther Weon

Most documentation tells users what your product does. Few guide them through it. User personas aren’t just “who the user is.” They show where users are in their journey and what they need at each stage. Miss that, and users struggle to find what they need. Learn how to create documentation that actually guides users: https://lnkd.in/d5wmt-as #TechnicalWriting #UserExperience #DocsAsCode #Documentation #UX

3

Your Vector Database Doesn't Understand Precision. Here's Why. Most teams treat embeddings like magic. Chunk your docs, embed them, query, done. Then production happens. Here's the uncomfortable truth: similarity search isn't comprehension. Embeddings capture rich semantic relationships, but matching isn't reasoning. When you search "what happened at the meeting about the budget," your vector DB returns chunks about budgets, chunks about meetings, and chunks about things that happened. What it can't do is reason across them. Modern embeddings handle word-level ambiguity well. "Deploy containers" and "deploy troops" produce different vectors. But ask your retrieval system to distinguish "don't restart the server" from "restart the server," and it falls apart. Negation, temporal reasoning, multi-hop inference: that's where embeddings hit their ceiling. No retrieval method fixes this, not even hybrid. That's the job of your LLM layer, which reasons over what retrieval surfaces. I've been building Beckett, a personal AI assistant running 24/7 on my VPS. Its memory system searches thousands of past conversations for relevant context. Here's what I learned: ~ Vector search alone works better than most think. Semantic search finds conversational context incredibly well. When Beckett needs "what did I say about my gym routine last week?" embeddings nail it. Low latency, simple to deploy. Trade-off: struggles with exact matches like "Feb 15th at 3 PM." ~ Hybrid retrieval closes the precision gap. Dense vectors find semantics. BM25 finds exact keywords, dates, IDs, specific terms. Together they cover the precision gap that neither handles alone. For conversational agents, vector-only is 80% quality for 20% complexity. You need hybrid when handling structured data, multi-language queries, or precision-critical lookups. ~ Architecture matters more than strategy. Whether vector-only or hybrid, move vectors into your database layer, not separate infrastructure. Simpler, more efficient, less operational burden. The teams shipping reliable AI agents in 2026 start simple, measure what breaks, add complexity only where it matters. What's your experience with vector vs. hybrid search? Drop your thoughts below. #VectorDatabases #SemanticSearch #RAG #AIEngineering #Supabase

1

I recorded a video on how to become a technical writer and how to create high-quality technical content. It covers how to get started, how to build writing samples, and how to write content that’s clear and useful, even if you’re starting from scratch. Watch it here: https://lnkd.in/dE2aJm_J And share with anyone that would find it useful!

140

10 Comments

Sreenshots can confuse your users. They say a picture is worth a thousand words. In technical writing, a bad screenshot is worth a thousand support tickets. If you just "snip and paste" your entire browser window into a doc, you aren't helping. You’re forcing the user to play a game of "Where’s Waldo?" with your interface. Here are the 3 Rules of Professional Screenshots to keep your docs clean and your maintenance low: 1. The "Crop of Truth" ✂️ Never show the whole screen if you are only talking about one button. Bad: A 1920x1080 shot of your entire desktop (including your messy bookmarks bar). Good: A tight crop around the specific UI element, with just enough "landscaping" (surrounding context) so the user knows where they are. 2. Annotate with Purpose ✏️ If you want someone to look at the "Save" button, put a box around it. But follow the "One Box" rule: Use a high-contrast color (usually bright red or orange). Use a consistent line weight. Don't over-annotate. If you have 5 arrows on one image, you need 5 separate images or a better UI. 3. Avoid the "Maintenance Trap" 🪤 Technical documentation ages quickly. To make your screenshots last longer: Blur out names, emails, and specific dates. Don't include the "v.1.0.4" footer in the corner if you don't have to. The "Empty State" Trick: Whenever possible, take screenshots of a clean, default state rather than a heavily customized one. The "Screenshot Maturity" Scale: Level 1: Taking a photo of your monitor with your phone (Never do this. Ever.) 🚫 Level 2: Full-screen snips with default file names. Level 3: Cropped, annotated, and named user-settings-save-button.png. Level 4: Using a tool like Snagit or CleanShot X to maintain a consistent style across the whole site. Takeaway this away A screenshot is an anchor for the reader’s eye. If the anchor is messy, the reader drifts. Keep it tight, keep it clean, keep it anonymous. LET ME HEAR FROM YOU What's in your toolkit? 🛠️ Every technical writer has a "ride or die" screenshot tool. Are you a Snagit power user? A CleanShot X fan? Or a Scribe automation wizard? Drop your favorite tool in the comments and tell us why it wins! 👇 #TechnicalWriting #UXDesign #ContentStrategy #Documentation #TechWritingTips #Series20

2

And good documentation for your product acts as a top-of-funnel driver, feeding search and LLMs so more people discover your product. Docs convince practitioners that your product is worth adopting. Those practitioners then convince the buyers. Good docs touch every single part of your customer lifecycle. And you probably don’t have enough full-time docs people to get all the benefits you could.

11

New post: 10 principles of the cyborg technical writer -- brief notes and bullet points on how to use AI to augment your role In my post "The Emerging Picture of a Changed Profession: Cyborg Technical Writers — Augmented, Not Replaced, by AI," I mentioned an upcoming presentation I'm giving to students and faculty. I argue that the future of the profession is the cyborg model, where machines augment our capabilities rather than replace us. In this post, I share notes about what skills a tech writer would need to learn to thrive in this world of augmentation. Read more: https://lnkd.in/g8Zfrbu2

123

9 Comments