<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ragina Jeon on Medium]]></title>
        <description><![CDATA[Stories by Ragina Jeon on Medium]]></description>
        <link>https://medium.com/@lyingdragon?source=rss-fdfb4f7981f0------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*4FgfE79F4HPds4UpSK8hTA.jpeg</url>
            <title>Stories by Ragina Jeon on Medium</title>
            <link>https://medium.com/@lyingdragon?source=rss-fdfb4f7981f0------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 04:12:17 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@lyingdragon/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Evaluating Technical Documentation]]></title>
            <link>https://lyingdragon.medium.com/evaluating-technical-documentation-a6956979e0e5?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/a6956979e0e5</guid>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[quality]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Wed, 04 Nov 2026 14:51:31 GMT</pubDate>
            <atom:updated>2026-11-04T14:51:31.067Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Korean version</strong></p><p><a href="https://lyingdragon.medium.com/%EA%B8%B0%EC%88%A0-%EB%AC%B8%EC%84%9C-%ED%8F%89%EA%B0%80%ED%95%98%EA%B8%B0-99a8b7b6ff08">기술 문서 평가하기</a></p><h3>How do we measure the quality and value of technical writing in the age of AI?</h3><p>While working as a technical writer, there’s a question that keeps coming up without any solid answer: “<strong>How should we evaluate a technical writer’s work?</strong>”</p><p>It’s a question management asks during performance review season, and it always pops up when technical writers get together to debate.</p><p>We can break this problem down into two parts.</p><ul><li>First, how much did the technical writer’s output contribute to the company?</li><li>Second, how much did the actual deliverables handled by the technical writer improve?</li></ul><p>The first refers to how much product sales or business performance changed because of the technical documentation, while the second refers to how much the technical writing itself — the documentation — actually got better.</p><h3>Evaluating Contribution</h3><p>The first part is just as hard to measure for technical writers as it is for any engineer or support staff belonging to a non-product team. For example, a recruiting team can evaluate the candidates they hire (their work output), but it’s hard to measure how much those hires actually increased company revenue. A security engineer can see how much a product’s security vulnerabilities (work output) have decreased, but measuring how much fixed costs were cut because of it is tough. Just like this, there are many roles where <strong>you can evaluate the output itself, but not the indirect contribution to the company as a whole</strong>.</p><p>Still, scraping the bottom of the barrel for ideas, a few methods have been proposed:</p><p>One approach is to measure contribution by looking at the number of customer inquiries or complaints — and the support team’s time spent handling them — comparing periods with and without documentation, or when providing docs that haven’t been touched by a technical writer versus ones that have. But customer inquiries and complaints are driven by more than just documentation, so if you’re unlucky, the metrics might actually look worse after deployment. Besides, sometimes companies don’t track customer complaints in the first place so there’s no baseline, or the deliverable is a one-off document or blog post that doesn’t generate direct inquiries. Another idea is using page views (PV) on technical docs to measure impact. While PV can indicate customer interest, it’s hard to prove a direct link saying interest grew <em>*because*</em> the documentation was well-written. If people are interested in a product, PV might go up even if the docs are written poorly. So, realistically, <strong>there’s no good way to measure how much a technical writer contributes to company revenue</strong>.</p><h3>Evaluating Deliverables</h3><p>The second part is a bit different. This is about seeing whether technical docs written by a technical writer explain the product more easily and accurately than those written by other roles, which is practically a measure of the technical writer’s competence. Because of this, discussions among technical writers have sometimes drifted toward using certifications. Apparently, the US has technical communication degrees and certifications that industry insiders recognize. Getting certified means you have technical writing skills, and you can trust that what you write will be reasonably good. However, since all deliverables produced by a single technical writer would receive the same evaluation, <strong>it’s essentially evaluating the person rather than the output</strong>. Another proposed method is surveying developers or product managers who worked with them. Compared to certifications, this is a bit subjective, and <strong>if you write bad survey questions, it easily gets distorted into an evaluation of the person</strong>. An experimental survey used at a former company had questions like, “Did the technical documentation improve after the technical writer joined?” or “Were requests handled well?” Anyone who has done peer reviews knows that if you have to keep working with that person, you’re likely to give them a good rating anyway.</p><p>So, is there really no way to evaluate the actual output instead of the person?</p><p>Fortunately, a few years ago at an overseas conference, I heard about test-based documentation evaluation. It’s applicable to executable, tutorial-style technical documentation: you build a program that directly runs the code and commands shown in the doc, and verify whether it runs without issues and proceeds exactly as the text describes. Recently, methods using AI to do similar kinds of verification have also been introduced.</p><p>However, as mentioned earlier, the types of documentation this works for are limited, and command-execution accuracy isn’t the entirety of technical document quality.</p><p>So, to sum it up, <strong>there hasn’t been a proper way to evaluate deliverables either — until now</strong>.</p><p>The introduction got pretty long with the phrase “how to evaluate a technical writer’s work.” As you’ve probably guessed, this was all a build-up to talk about “<strong>the quality of technical documentation</strong>.”</p><p>If we had a quantitative way to measure that a technical document was well-written (the first part), we could eventually use it when a method arises to prove that those well-written docs actually contributed to company revenue (the second part).</p><h3>Technical Documentation Quality in the AI Era</h3><p>Quality evaluation is even more necessary in the age of AI. If we leave documentation writing to AI, we need to check if the AI wrote it properly. But if humans try to do that, we’ll run into the “human bottleneck” situation that’s trending everywhere lately. On the flip side, if we build a way to evaluate documentation quality and use it to score AI-written text, humans only need to review the substandard outputs. Also, to look at quality, tracking the trend of improvement over time matters more than a snapshot at a specific moment, which requires periodically evaluating quality under the same conditions. If humans had to do this, it would become a bottleneck, but with proper measurement criteria, we can hand off repetitive evaluation tasks to AI.</p><p>To sum it up, in the AI era, AI writes the docs, AI evaluates the quality to decide whether a human needs to look at them, and a quality dashboard lets us see if human intervention is actually improving the docs.</p><h3>Evaluation Criteria &amp; Metrics</h3><p>To tell AI to evaluate documents, we need to set evaluation criteria. To do that, we have to figure out what matters most in technical documentation and how to measure it. I’ve already laid out what matters in the titles of the three sections in Part 2 of my book, &lt;Who Says Developers Can’t Write? <em>(Korean book)&gt;</em>:</p><blockquote>Accuracy, Conciseness, and Completeness.</blockquote><p>Accuracy means writing things without errors, conciseness means making things easy to understand, and completeness means covering everything that needs to be included. In fact, these three are the ultimate goals of technical writing.</p><p>So how do we judge whether something is written accurately, concisely, and completely?</p><p>Our team divided each item into generic metrics (which can be measured regardless of the product) and product metrics (which require product knowledge). Generic metrics include freshness, consistency, readability, structure, and AI readiness. Product metrics include feature coverage, information architecture, and cross-doc consistency. Information architecture and cross-doc consistency are similar to generic metrics and haven’t been discussed in detail within the team yet, so I’ll leave them out for now. Connecting just the discussed metrics to the ultimate goals of technical writing looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aQGzrE4CU2Y5uvd1bGOuMw.png" /></figure><p>As you can see, all metrics tie back to accuracy, conciseness, and completeness.</p><p>To elaborate, personally, I think “writing to be easily understood by humans” has lost its meaning in the AI era. Do we really need to consider human readability when humans are reading technical docs less and less? Humans have varying levels of knowledge and attention spans, so we used to need to explain things as simply as possible and structure explanations for the human brain (e.g., avoiding listing more than 5 things at once). But <strong>AI knows more than humans and doesn’t lose focus, so why bother putting effort into human readability?</strong> (Though people say AI forgets parts if the text is too long, unfortunately, improving readability in technical writing isn’t just about shortening the length.)</p><p>Taking it a step further, <strong>do we even need to consider AI readability? </strong>With advancing models, we often hear that “even if you write like trash, AI figures it out brilliantly.” I’ve heard stories where people built templates for AI to read easily, but when a new model came out, it read it just fine even without the templates. Between templates and what I covered a few months ago in my post &lt;<a href="https://lyingdragon.medium.com/writing-for-ai-caab3344f279">Writing for AI</a>&gt;, methods for improving AI readability focus on format or expression, but since many models now read fine regardless of format or expression, it might no longer be valid. However, the method of optimizing for RAG search — which I touched on partly in writing for AI — is still valid. It’s meant to boost discoverability, which is always cited as a problem in technical docs. In short, <strong>even if techniques for making things easy for AI to understand are no longer valid, techniques for making things easy to search via AI are still worth considering</strong>. Our team grouped AI readability and AI searchability together under “AI readiness,” and I feel like we could probably drop AI readability going forward.</p><blockquote>You might wonder why discoverability isn’t in the metrics, but I don’t think ‘discoverability’ is a metric of document quality itself. Making documents easy to find requires tweaking company doc culture, policies, infrastructure, and engineering rather than the documents themselves. Therefore, while discoverability is a must-consider factor when planning technical documentation, it’s not appropriate as a document evaluation metric. However, I believe writing techniques to enhance AI searchability from a document creation standpoint are still worth researching.</blockquote><p>After writing the blog post shared earlier, our team did some research on finding document quality metrics, and a presentation about document quality came up at an overseas conference recently as well:</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FSukzYz09w6Q%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DSukzYz09w6Q&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FSukzYz09w6Q%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/f2b87f15e5c4395fa4322dfef58ad09c/href">https://medium.com/media/f2b87f15e5c4395fa4322dfef58ad09c/href</a></iframe><p>The speaker is a technical writer at Booking.com, and she presented five metrics that, interestingly, look very similar to our team’s results.</p><figure><img alt="" src="https://cdn-images-1.medium.com/proxy/1*DDAQbouTivPJ0XmYM5aMAA.png" /></figure><p>The metrics that differ from ours are style and discoverability. I already explained why we didn’t include discoverability, so let’s talk about the style metric.</p><p>Booking.com made adherence to a style guide a key metric, which I think is necessary for publicly facing docs. In an era where AI reads and writes documentation, document style doesn’t matter as long as the content is accurate, but nevertheless, <strong>public docs affect company reputation and brand, so you still have to maintain standards</strong>. That’s probably why Booking.com included the style metric. However, since our team researched quality metrics to design an internal document management process for the AI era, whether style guidelines were strictly followed wasn’t included as a metric. That said, since the consistency metric includes items you’d typically find in a style guide, like “using consistent terminology,” we can’t say style scores are entirely absent.</p><p>Ultimately, while our metrics differ slightly depending on our respective goals, the items and meanings we want to measure are practically the same. If we get into the detailed measurement methods, it probably feels even more similar.</p><p><strong>If you ask me which of these many metrics is the most important, it’s freshness, consistency, and feature coverage</strong>. In terms of technical writing techniques, it boils down to two things, excluding conciseness (=readability) as mentioned earlier: accuracy and completeness. As long as you</p><ol><li>Cover everything that needs to be addressed,</li><li>write it without errors, and</li><li>deliver it on time</li></ol><p>it doesn’t matter if the document is in Korean or Arabic, formatted in Markdown or MS Word, or written in formal, informal, or rough prose. AI will read it just fine anyway.</p><h3>How to Measure Metrics</h3><p>How our team measures each metric is a story for another time since it takes a while to explain. Instead, let’s compare some of Booking.com’s measurement methods with ours. (You can check how Booking.com measures each metric in their video.)</p><p>Booking.com identifies product features and measures the coverage metric by checking whether conceptual, procedural, and reference documentation exists for each feature. I was surprised to find it almost identical to our team’s thinking. The only slight difference is that in our team, some argued that document types don’t necessarily equal feature explanations. Much like doubting the validity of readability, we questioned whether document types are still valid in the AI era. So we considered a method that looks at actual content mentions alongside document types.</p><p>Booking.com apparently didn’t use traditional readability scores because they felt they didn’t fit technical docs, instead defining their own “visual conciseness” (which you can find in my book) for the readability metric. They also evaluate page layout and overall information architecture (IA) as readability metrics, which matches our team’s structure and information architecture metrics.</p><p>Booking.com measures discoverability based on whether an AI agent can read the docs and accurately answer questions in an FAQ. Interestingly, our team uses a similar approach for our AI readability metric. In a RAG system built on internal tech docs, part of the AI readability score is based on how closely the AI’s technical answers match the ground truth written by the owner. We didn’t build this part, so we just use that value as-is, while our team calculates the final score by measuring whether it complies with the format/expression guidelines covered in the blog post mentioned earlier. In a way, what Booking.com calls discoverability, we call AI readiness/AI readability.</p><h3>How to Use Metrics</h3><p>You might be wondering where to use these metrics. As mentioned earlier, they can serve the following roles:</p><ul><li>A gate to evaluate AI-written documents and decide whether humans need to review them</li><li>A dashboard showing the trend of internal technical documentation improvements</li><li>(Bonus) A guide that evaluates documents and provides feedback on how to improve them</li></ul><p>If automated, a quality evaluation agent could measure each metric, summarize how to route and improve the target docs, send substandard docs to humans, and pass the rest to the documentation writing agent for automatic improvement based on the guide. You can also get a snapshot at a glance of which documents improved by how much over time, which ones are up to date, and so on.</p><p>When you think about it, it’s nothing groundbreaking. It’s everything we already do in software development, just replacing code with documentation. Just as developers are great at writing code, so they orchestrate dev-focused AI agents and build harnesses, <strong>technical writers are great at writing docs, so it’s only natural for technical writers to orchestrate doc-focused AI agents and build harnesses. As I’ve said many times, this is the path technical writers should take in the AI era.</strong></p><h3><strong>Next Steps</strong></h3><p>Personally, my team tried building this, but we hit pause due to organizational direction and headcount issues. But I’m not stopping here — I’m going to try building it at my new company.</p><p>Sometimes doing new things makes your heart feel full, and one of those moments is realizing that other people are doing the exact same work you’ve been pursuing. Knowing that gives me the comfort of knowing, “My direction wasn’t wrong.” Seeing Booking.com’s presentation gives me a little reassuring peace of mind once again.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a6956979e0e5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[기술 문서 평가하기]]></title>
            <link>https://lyingdragon.medium.com/%EA%B8%B0%EC%88%A0-%EB%AC%B8%EC%84%9C-%ED%8F%89%EA%B0%80%ED%95%98%EA%B8%B0-99a8b7b6ff08?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/99a8b7b6ff08</guid>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[quality]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Wed, 04 Nov 2026 14:33:12 GMT</pubDate>
            <atom:updated>2026-11-04T14:33:12.856Z</atom:updated>
            <content:encoded><![CDATA[<p>테크니컬 라이터로 일하는 동안 꾸준히 이야기는 나왔지만 이렇다 할 답이 나오지 않은 문제가 있다. 바로 <strong>“테크니컬 라이터의 업무를 어떻게 평가할 것인가”</strong>다.</p><p>팀 평가 시즌에 상부에서 묻기도 하고, 테크니컬 라이터들이 토론할 때도 등장하는 문제인데, 답은 둘로 나눠 볼 수 있다.</p><ul><li>첫째, 테크니컬 라이터의 결과물이 회사에 얼마나 기여했는가</li><li>둘째, 테크니컬 라이터가 직접 손댄 결과물이 얼마나 개선되었는가</li></ul><p>첫 번째는 그 기술 문서로 인해 제품 매출이나 업무 성과가 얼마나 좋아졌는지를 말하며, 두 번째는 테크니컬 라이팅 결과물, 즉 기술 문서가 얼마나 개선되었는지를 말한다.</p><h3><strong>기여도 평가</strong></h3><p>첫 번째는 테크니컬 라이터뿐만 아니라, 제품팀이 아닌 곳에 소속된 모든 엔지니어/서포터 입장에서도 똑같이 측정하기 어렵다. 예를 들어, 채용팀이라면 채용 인재 평가는 할 수 있지만 그 인재를 채용해서 회사 매출이 얼마나 늘었는지는 측정하기 어렵다. 보안 엔지니어라면 제품의 보안 취약성이 얼마나 줄었는지 알 순 있지만 그 덕분에 회사 고정비가 얼마나 줄었는지는 측정하기 어렵다. 이처럼, <strong>결과물 자체는 평가할 수 있어도 회사 전체의 간접적인 기여도를 평가할 수 없는 </strong>직무가 많다.</p><p>그래도 굳이 아이디어를 쥐어짜, 아래와 같은 방안이 제시되기도 했다.</p><p>기술 문서가 없을 때와 있을 때, 혹은 테크니컬 라이터가 손보지 않은 문서를 제공할 때와 손보지 않은 문서를 제공할 때의 고객 질의나 불만 개수, 그에 대응하는 지원팀의 투입 시간으로 기여도를 측정하는 방안이 그중 하나다. 하지만 고객의 질의 수와 불만 수에 미치는 요소가 기술 문서뿐만은 아니어서, 운이 없다면 오히려 투입 후에 측정한 결과가 더 나빠질 수도 있다. 애초에 고객의 불만 수를 측정하지 않아서 비교군이 없거나, 1회성 제출 문서나 블로그가 결과물이어서 고객 질의가 없는 경우도 있고. 또 하나는, 기술 문서의 PV(page view)로 결과물의 기여도를 평가하는 방안이다. PV가 고객의 관심도를 의미할 순 있지만, 기술 문서를 잘 쓴 덕택에 관심도가 올랐다는 연결 관계를 증명하기 어렵다. 제품에 관심이 있다면 문서를 아무렇게나 쓰더라도 PV가 늘어날 수 있으니까. 따라서 <strong>테크니컬 라이터가 회사 매출에 얼마나 기여했는지를 측정하는 방법은 마땅히 없었다</strong>고 봐야겠다.</p><h3><strong>결과물 평가</strong></h3><p>두 번째는 조금 다르다. 테크니컬 라이터가 쓴 기술 문서가 다른 직무 종사자가 쓴 기술 문서보다 제품을 더 쉽게, 더 올바로 설명하는지 보겠다는 말인데, 살짝 돌려보면 테크니컬 라이터의 역량 측정에 가깝다. 그러다 보니 테크니컬 라이터 간 토론에서 자격증 이야기도 나왔다. 미국에는 테크니컬 커뮤니케이션 전공도 있고 관련 종사자들은 알만한 자격증도 있다고 한다. 그 자격증을 따면 테크니컬 라이팅 역량이 있다는 뜻이고 그 사람이 쓴 글은 어느 정도 잘 썼을 것으로 믿을 수 있을 테다. 다만, 한 테크니컬 라이터가 쓴 모든 결과물이 같은 평가를 받게 되므로 <strong>사실상 사람 평가지 결과물 평가라고 할 수 없다</strong>. 또 하나 제안된 방법은, 함께 일한 개발자나 기획자에게 설문하는 건데, 자격증에 비하면 조금 주관적인 데다 설문 항목을 잘못 만들면 똑같이 사람 평가로 왜곡될 수 있다. 회사에서 실험적으로 사용했던 설문에는 “테크니컬 라이터가 투입되어 기술 문서가 좋아졌습니까”나 “요청 사항을 잘 처리했습니까” 같은 문항이 있었는데, 동료 평가를 해본 사람이라면 알겠지만 어차피 계속 일할 동료라면 좋은 평가를 줄 가능성이 높다.</p><p>그렇다면 사람 평가가 아니라 진짜 결과물을 평가하는 방법은 전혀 없을까?</p><p>다행히, 수년 전 해외 컨퍼런스에서 테스트 기반 문서 평가에 관한 내용을 들은 적 있다. 실행 가능한 튜토리얼형 기술 문서에 적용할 수 있는 건데, 문서에 나온 코드와 명령어를 직접 실행하는 프로그램을 만들고 프로그램에 따라 실행했는데 문제가 없는지, 문서 설명대로 진행되는지를 검증하는 방법이다. 최근에도 AI를 활용해서 유사한 방법으로 검증하는 방법이 발표되기도 했다. 다만, 앞서 말한 대로 가능한 문서가 제한적이며, 명령 실행 정확도가 기술 문서 품질 전부라고 할 순 없다.</p><p>따라서 <strong>결과물 평가 역시 여태까지는 마땅한 방법이 없었다</strong>고 정리할 수 있다.</p><p>“테크니컬 라이터의 업무를 평가하는 방법”이라는 말로 서론이 길었다. 눈치챘겠지만, 이건 결국 <strong>“기술 문서의 품질”</strong> 이야기를 하기 위한 빌드업이다.</p><p>기술 문서를 잘 썼다는 정량적 평가(결과물 평가)가 있다면, 훗날 잘 쓴 기술 문서 덕분에 회사 매출에 기여했다는 사실(기여도 평가)을 증명하는 방법이 떠오를 때 활용할 수도 있다.</p><h3><strong>AI 시대 기술 문서 평가</strong></h3><p>품질 평가는 AI 시대에는 더욱 필요하다. AI에 문서 작성을 맡긴다면 AI가 제대로 썼는지 확인해야 하는데, 그걸 사람이 하기엔 요즘 유행처럼 번지는 “사람이 병목” 상황이 벌어질 것이다. 반대로 기술 문서 품질을 평가하는 방법을 만들어 AI가 쓴 글을 평가한다면, 기준 이하의 결과물만 사람이 살펴보면 된다. 또, 품질을 살피려면 특정 시점의 상태보다는 기간 중 개선 추이가 중요한데, 그러려면 같은 조건에서 주기적으로 품질을 평가해야 한다. 이 일 역시 사람이 하면 병목이 되는데 측정 기준만 있다면 AI에게 반복 평가 작업을 맡길 수 있다.</p><p>정리하자면, AI 시대에는 AI가 문서를 작성하고, AI가 품질을 평가해 사람이 볼지 말지 결정하고, 품질 대시보드로 사람의 작업이 실질적으로 문서를 개선하는지 보기 위해 품질 평가가 필요하다.</p><h3><strong>평가 지표</strong></h3><p>AI에 문서를 평가하라고 지시하려면 평가 기준을 세워야 한다. 그러자면 기술 문서에서 무엇이 중요한지를 판단하고 그것을 어떻게 측정할지를 정해야 한다. 일단 무엇이 중요한지는 내가 쓴 책 <a href="https://product.kyobobook.co.kr/detail/S000218400404">&lt;개발자는 글을 못 쓴다고요&gt;</a>의 Part 2의 섹션 제목에 적어놨다.</p><blockquote>정확성, 간결성, 완결성.</blockquote><p>정확성은 틀리지 않게 쓰는 것, 간결성은 이해하기 쉽게 쓰는 것, 완결성은 있어야 할 내용을 다 쓰는 것을 말한다. 사실 이 세 가지는 테크니컬 라이팅의 궁극적 목표이기도 하다.</p><p>그렇다면 틀리지 않게 썼는지, 이해하기 쉽게 썼는지, 있어야 할 내용이 다 있는지를 어떻게 판단할까?</p><p>우리 팀은 각 항목을 제품과 무관하게 측정할 수 있는가와 제품 정보를 알아야만 측정할 수 있는가에 따라 일반 지표와 제품 지표로 나눠 생각했다. 일반 지표에는 최신성(freshness), 일관성(consistancy), 가독성(Readability), 구조 적확성(structure), AI 대응성(AI readiness)을, 제품 지표에는 기능 커버리지(feature coverage)와 정보 구조(information architecture), 문서 세트 일관성(cross-doc consistancy)을 뒀다. 정보 구조와 문서 세트 일관성은 일반 지표의 몇 가지와 유사하고, 팀 내에서도 아직 구체적인 방안을 논의하지 않았기에 일단 제외하고, 논의한 지표만 테크니컬 라이팅의 궁극적 목표와 연결하자면 이렇다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ac5s8z8l2oAVhNFnI-QGKg.png" /></figure><p>모든 지표가 정확성, 간결성, 완결성과 이어지는 걸 알 수 있다.</p><p>부연하자면, 개인적으로는 AI 시대에 ‘이해하기 쉽게 쓰기’는 의미가 옅어졌다고 생각한다. 점점 사람이 기술 문서를 읽지 않게 되는 마당에 사람을 위한 가독성을 고려해야 할까? 사람은 가진 지식과 집중력에 따라 이해도가 달라지므로 최대한 쉽게 풀어쓰고, 사람의 뇌가 파악하기 쉽도록 설명을 구성할 필요가 있었다. 그런데 <strong>AI는 사람보다 아는 게 많고 집중력이 떨어질 일도 없는데 굳이 가독성을 높이는 데 품을 들여야 할까</strong>? (AI도 내용이 너무 길면 일부 잊는다고는 하지만, 아쉽게도 테크니컬 라이팅에서 가독성을 높이는 방법은 단순히 내용 길이를 줄이는 것만이 아니다.)</p><p>좀 더 나아가면, <strong>AI를 위한 가독성도 고려하지 않아도 되지 않을까?</strong> 모델이 발전하면서 “개떡같이 써도 찰떡같이 알아듣는다”는 이야기를 많이 듣는다. AI가 잘 읽는 구조로 템플릿을 만들었는데 새 모델이 나오자 템플릿 대로 안 써도 잘 읽더라는 이야기도 들었다. 템플릿도 그렇고, 몇 달 전에 작성했던 <a href="https://lyingdragon.medium.com/ai%EB%A5%BC-%EC%9C%84%ED%95%9C-%EA%B8%80-%EC%93%B0%EB%8A%94-%EB%B2%95-da2856dee6e1?sharedUserId=lyingdragon">&lt;AI를 위한 글 쓰는 법&gt;</a>에서 다룬 내용도 그렇고, AI의 가독성을 높이는 법은 포맷이나 표현 개선인데, 포맷이나 표현에 무관하게 잘 읽는 모델이 많아져서 이제는 유효하지 않을 수 있다. 하지만, AI를 위한 글쓰기에서 일부 다룬, RAG에서 검색이 잘 되게 하는 방법은 여전히 유효할 수 있다. 늘 기술 문서의 문제점으로 거론되는 발견성(discoverability)을 높이기 위해서다. 즉, <strong>AI가 이해하기 쉽게 쓰는 기법은 유효하지 않더라도, AI로 검색하기 쉽게 만드는 기법은 여전히 고려할 만하다</strong>. 팀에서는 AI 가독성과 AI 검색성을 함께 묶어 AI 대응성(AI readiness)으로 칭했는데, 앞으로 AI 가독성은 빼도 되지 않을까 싶다.</p><blockquote>“발견성”이 왜 지표에 없느냐고 궁금해할 것 같은데, 발견성이 문서 자체 품질이라고 생각하지 않아서다. 문서를 잘 찾게 만들려면 문서 자체보다는 회사의 문서 문화와 정책, 인프라, 엔지니어링에서 손을 봐야 하기 때문이다. 따라서 발견성은 기술 문서를 기획할 때 반드시 고려할 요소지만 문서 평가 지표로 삼기엔 적절하지 않다. 하지만 문서 작성 측면에서 AI 검색성을 높이기 위한 글쓰기 기법은 계속 연구할 가치가 있다고 믿는다.</blockquote><p>주제로 돌아와서, 앞서 공유한 <a href="https://lyingdragon.medium.com/ai%EB%A5%BC-%EC%9C%84%ED%95%9C-%EA%B8%80-%EC%93%B0%EB%8A%94-%EB%B2%95-da2856dee6e1?sharedUserId=lyingdragon">블로그 글</a>을 적은 이후로 팀에서 문서 품질 지표를 연구해왔는데, 얼마 전 해외 컨퍼런스에서도 문서 품질 관련 발표가 있었다.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FSukzYz09w6Q%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DSukzYz09w6Q&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FSukzYz09w6Q%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/f2b87f15e5c4395fa4322dfef58ad09c/href">https://medium.com/media/f2b87f15e5c4395fa4322dfef58ad09c/href</a></iframe><p>발표자는 Booking.com 테크니컬 라이터로, 여기서 다섯 가지 지표를 제시했는데 재미있게도 우리 팀 결과와 비슷하다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DDAQbouTivPJ0XmYM5aMAA.png" /></figure><p>우리와 다른 지표는 스타일과 발견성이다. 발견성 지표를 왜 넣지 않았는지는 위에서 설명했으므로, 스타일 지표만 이야기해 보자.</p><p>Booking.com은 스타일 가이드를 지키는 걸 주요 지표로 삼았다. 나는 AI가 문서를 읽고 쓰는 시대에는 내용이 정확하다면 문서 스타일은 중요하지 않다고 생각하지만, 그럼에도 불구하고 <strong>외부 공개 문서는 회사의 평판과 브랜드에 영향을 미치므로 여전히 지킬 것은 지켜야 한다</strong>. 그렇기에 Booking.com이 스타일 지표를 포함한 이유를 알 것 같다. 하지만 우리 팀은 AI 시대 내부 문서 관리 프로세스를 설계하고자 품질 지표를 연구했기에 스타일 가이드를 지키느냐 아니냐는 지표에 넣지 않았다. 그래도 일관성 지표에서 ‘일관된 용어 쓰기’ 같이 스타일 가이드에 나옴직한 항목이 있으므로 스타일 점수가 전혀 없다곤 할 수 없다.</p><p>따지고 보면 서로가 가진 목표에 따라 지표가 조금 다르긴 하지만, 측정하고자 하는 항목이나 의미는 거의 같다고 볼 수 있다. 상세한 측정 방법을 이야기하다 보면 아마 더 비슷하다고 느낄 것이다.</p><p>이 많은 지표 중에 무엇이 제일 중요하냐고 묻는다면, <strong>최신성과 일관성, 기능 커버리지</strong>라는 게 시대적 대답이다. 테크니컬 라이팅 기법으로 따지자면, 결국 앞서 말한 대로 간결성(=가독성)을 제외한 두 가지, 정확성과 완결성으로 결론 낼 수 있다.</p><ol><li>다뤄야 할 모든 내용을,</li><li>틀리지 않게,</li><li>제시간에</li></ol><p>기술하기만 한다면, 그 문서가 한국어건 아랍어건, 포맷이 마크다운이건 MS Word건, 경어건 반말이건 음슴체건 상관없다. 어차피 AI는 잘 읽을 테니까.</p><h3><strong>지표 측정하는 법</strong></h3><p>우리 팀이 각 지표를 어떻게 측정하는지는, 좀 더 길게 다뤄야 할 내용이니 다음 기회로 미루겠다. 대신 Booking.com의 측정 방법 일부를 우리 팀 측정 방법과 비교해 보자. (Booking.com이 각 지표를 어떻게 측정하는지는 영상에서 볼 수 있다.)</p><p>Booking.com은 제품의 기능을 식별한 후 각 기능에 개념형, 절차형, 레퍼런스형 문서가 있는지를 판단해 커버리지 지표를 측정한다. 우리 팀 생각과 거의 일치해서 깜짝 놀랐다. 살짝 다른 점이라면, 우리 팀에서는 문서 유형이 곧 기능 설명이라고 하기는 어렵다는 의견이 있었다. 가독성의 유효 여부를 의심한 것과 마찬가지로, AI 시대에 문서 유형이 유효한가 하는 의문이 들어서다. 그래서 문서 유형뿐만 아니라 실제 내용 언급을 판단하는 방식을 함께 고려했다.</p><p>Booking.com은 전통적인 가독성 점수가 기술 문서에 맞지 않다고 생각해 사용하지 않았다고 한다. 대신 가독성 지표를 위해 시각적 간결성(내 책 &lt;개발자는 글을 못쓴다고요?&gt;에서 볼 수 있다)을 자체 정의해서 사용했다. 또, 페이지 구조나 전체 문서 정보 구조(information architecture, IA)를 가독성 지표로 평가하는데, 이는 우리 팀 지표의 구조 적확성 및 정보 구조와 일치한다.</p><p>Booking.com의 발견성은, AI 에이전트가 문서를 읽고 FAQ에 담긴 질문을 잘 대답하느냐로 측정한다. 재미있게도 우리 팀은 AI 가독성 지표로 유사한 방식을 사용한다. 사내 기술 문서로 구축한 RAG 시스템에서, 기술 질문에 대해 담당자가 작성한 올바른 응답(ground truth)과 얼마나 유사한 답변을 하느냐가 AI 가독성 점수 일부다. 이건 우리 팀이 만들지 않아서 그냥 가져다 쓰는 값이고, 우리 팀은 앞서 소개한 블로그에 작성했던 포맷/표현 방법을 준수하는지를 측정해서 최종 점수를 매긴다. Booking.com이 발견성으로 제시한 지표를, 우리는 AI 가독성이라고 부르는 셈이다.</p><h3><strong>지표 활용하는 법</strong></h3><p>이 지표를 어디에 활용할까 하는 의문이 들지도 모르겠다. 앞에서 일부 말했는데, 다음 역할로 쓸 수 있다.</p><ul><li>AI가 작성한 문서를 평가해 사람이 손볼지 말지를 판단하는 게이트</li><li>사내 기술 문서 개선 추이를 보여주는 대시보드</li><li>문서를 평가하며 개선 방향을 알려주는 가이드</li></ul><p>자동화한다면, 품질 평가 에이전트가 각 지표를 측정하면서 대상 문서를 어떻게 개선할 수 있는지 정리하고, 기준 이하 문서를 사람에게 전달하고, 나머지는 문서 작성 에이전트에 넘겨 가이드에 따라 자동 개선한다. 기간별로 어떤 문서가 얼마나 개선되었으며, 어떤 문서가 최신인지 아닌지 등을 한눈에 파악할 수도 있다.</p><p>가만 보면 별로 새로울 것도 없다. 코드를 문서로 바꾸기만 하면 전부 개발할 때 하는 일이니까. 코드를 작성하는 건 개발자가 잘하므로, 개발자가 개발용 AI 에이전트를 오케스트레이션하고 하네스를 구성하듯, <strong>기술 문서를 작성하는 건 테크니컬 라이터가 잘하므로, 테크니컬 라이터가 문서용 AI 에이전트를 오케스트레이션하고 하네스를 구성하는 게 당연하다. 여러 차례 말해왔던 대로 AI 시대 테크니컬 라이터가 가야 할 길이다.</strong></p><h3><strong>다음 할 일</strong></h3><p>개인적으로는 팀에서 이걸 만들려다가 조직 방향성과 인력 문제로 잠시 멈췄다. 하지만 난 여기서 멈추지 않고 새로운 회사에서 해보려고 한다.</p><p>이런저런 새로운 일을 하며 마음이 뿌듯해질 때가 가끔 있는데, 그중 하나는 내가 해온 일을 다른 곳에서도 한다는 걸 알게 될 때다. 그걸 알고 나면 “내 방향이 틀리지 않았구나”는 위안을 얻기 때문이다. Booking.com에서 발표한 내용을 보면서 이번에도 살짝 안심해 본다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=99a8b7b6ff08" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[개발자에서 문서 엔지니어로 — 내 회사 생활]]></title>
            <link>https://lyingdragon.medium.com/%EA%B0%9C%EB%B0%9C%EC%9E%90%EC%97%90%EC%84%9C-%EB%AC%B8%EC%84%9C-%EC%97%94%EC%A7%80%EB%8B%88%EC%96%B4%EB%A1%9C-%EB%82%B4-%ED%9A%8C%EC%82%AC-%EC%83%9D%ED%99%9C-aaf2267005db?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/aaf2267005db</guid>
            <category><![CDATA[engineering-documents]]></category>
            <category><![CDATA[technical-writing]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sun, 30 Aug 2026 15:03:26 GMT</pubDate>
            <atom:updated>2026-08-30T15:03:26.316Z</atom:updated>
            <content:encoded><![CDATA[<p>첫 회사를 다닐 때를 떠올려 보면 정말 길고도 길었는데, 햇수로 따져보니 겨우 2년 남짓이다. 반면 지금 회사는 8년 가까이 다녔는데도 고작 몇 년 밖에 안된 기분이고.</p><p>30~40년씩 회사를 다니신 부모님을 보며 어떻게 그렇게 오래 한 직장을 다닐 수 있었을까 감탄하곤 했는데, 어느덧 나도 벌써 20년이 넘은 프로 회사원이라니. 시간이 흐르는 걸 못 느낀 채 (혹은 일부러 무시했을 수도) 아직 10년 차 정도라고 생각하다 보니 놓치고 있었지만, 이쯤 되면 한 번쯤 내 경력을 돌아봐도 되지 않을까.</p><p>그래, 짧지 않은 21년 회사 생활, 나는 내가 바라던 길을 잘 걸어왔을까?</p><h3><strong>꿈과 직장</strong></h3><p>초등학생 시절의 꿈은 소설가였다. 고등학생 때는 잠깐이나마 물리학자를 꿈꾸기도 했고. 하지만 대학 진학을 앞두고 컴퓨터를 선택했다. 어릴 때부터 컴퓨터를 배웠고, 게임하느라 손에서 놓은 적이 별로 없으니 어쩌면 자연스러운 선택일지도.</p><p>졸업할 무렵에는 “이제 뭘 하고 싶은가?”보다 “무슨 일을 해야 안정적으로 일할 수 있는가?”가 더 중요했다. 소설가나 물리학자, 또는 내가 그렇게 좋아하던 게임 만드는 일은 모두 불안정하고 돈을 벌기 어려운 직업 같았다. 심지어 당시에는 대기업도 마냥 안정적인 직장은 아니어서, 공기업이나 금융권에 가고 싶어 수없이 원서를 넣고 면접을 보러 다녔다. 소규모 공기업과 대기업, 국책은행 세 곳에 합격했는데, 가장 안정적이고 돈도 많이 줄 것 같은 국책은행을 선택했다.</p><p>지금의 나라면 <strong>“야, 그 길 아냐”</strong> 하고 말리겠지만, 미래를 몰랐던 그때의 나는 안정적인 회사 생활을 하고 싶어서 무작정 은행에 들어갔고, 6개월 만에 나왔다. 돌이켜보면 은행과 나는 애초에 너무 안 맞았다.</p><ul><li>첫째, 서비스직이란 환경</li><li>둘째, 보수적인 문화</li></ul><p>학교 선생님께도 그건 아니지 않느냐며 따지던 내가 그런 분위기에 적응할 수 있을 리가.</p><p>(부연하자면, 은행 전산직이었지만 정책상 창구 업무를 몇 년간 해야 했는데 그 일을 하면서 보수적이라고 느꼈다. 어쩌면 전산팀 분위기는 다를 수도 있고, 창구 업무도 요즘엔 많이 달라졌을 수 있다.)</p><h3><strong>안정적인 회사의 로망과 괴리</strong></h3><p>그 후엔 대기업 연구소에 들어갔는데, 뜻밖에도 재미있었다. 매일매일 회사에 가는 일이 즐거웠고, 동료들과도 잘 맞아서 지금도 가끔 연락한다.</p><p>문제는 연구소 프로젝트가 취소되면서였다. 연구소 멤버 전원이 타 연구소나 사업부로 전배 되자, “역시 대기업은 위험해. 안전한 곳이 최고야” 병이 재발해 또다시 여기저기 원서를 넣은 끝에 국책 연구소에 들어갔다.</p><p>아무래도 새로운 분야다 보니, 새로 배운 기술도 있고 이따금 일에 재미도 느꼈다. 다만, IT 중심 연구소가 아닌 데다 장기 프로젝트에 집중해 변화가 극히 적은 게 문제였다.</p><p>대학 동기들이 안드로이드를 이용한 최신 모바일 기술에 관해 나누는 이야기를 듣고 있자니, 나 혼자 뒤처지는 기분이었다. 게다가 수년째 반복하는 일도 지겹고 새로운 기회가 없는 것도 답답해서, 결국 그 안정적인 (가만히 있어도 정년까지 다닐 수 있는) 회사를 관두고 대기업으로 돌아갔다.</p><p>거기까지가 내 직장 생활 초반 6년인데, 그 경험을 통해 깨달은 바가 있다.</p><p>나는 <strong>안정적이지만 보수적인 환경에서는 재미를 느끼지 못했다</strong>. 오히려 불안정할지라도 비교적 열린 분위기의 사기업에서 훨씬 즐겁게 일했다. 분석해 보자면, 어린 시절에 학습되었을, “안정성에 대한 집착” 때문에 내 성향과는 전혀 맞지 않는 회사를 목표했던 셈이다.</p><p>물론 그 시간이 아깝진 않다. 그 경험 덕분에 내가 어떤 곳에 잘 맞는지 알게 됐으니까. 그 경험이 아니었다면, 어쩌면 지금쯤 다시 안정적인 회사를 찾으려 하지 않았을까?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HDbUHCNPRvRvgjqb-QCG_Q.png" /></figure><h3>6년 사이의 변화</h3><p>21년간의 회사 생활 중에서 나는 6년은 개발자, 나머지 15년은 에반젤리스트, 테크니컬 라이터, 문서 엔지니어라는 직무를 뒤섞어 일했다.</p><p>재미있게도, 내가 안정적인 회사를 찾아 방랑하던 시절은 딱 개발자 시절이었다. 그때는 주니어라 그랬는지, 딱히 “내가 이런 걸 해 보고 싶다”는 생각이 강하지 않아서 주어진 일을 해내는 데 집중했다. 개발 자체가 재미있어서 무엇을 해도 그냥 즐거웠던 것 같다. 국책 연구소에서는 이러저러하게 바꿔보자는 제안을 해본 적도 있지만, “잘 돌아가는 것을 굳이 바꾸지 말자”는 분위기라 새로운 시도를 하기 어려웠다.</p><p>반대로 기술 문서 쪽으로 직무 전환한 후에는, 직무 특성인지 아니면 시니어급이 된 덕분인지 몰라도 상황이 달라졌다.</p><p>팀에 해결해야 할 과제는 있지만 구체적인 방법은 정해져 있지 않아, 내가 방법을 고민해 제안할 기회가 많고 하고 싶은 대로 해볼 수도 있었다. 주어진 일도 했지만, 시간이 갈수록 시킨 일을 하기 보단, 어떤 방식으로 일할지, 어떤 과제를 만들어갈지 고민하게 되었다.</p><h3><strong>외부 제공 문서와 문서 엔지니어링</strong></h3><p>그때 내 주 업무는 에반젤리스트로서 회사의 플랫폼을 외부 개발자에게 알리는 일이었다. 그래서 외부 개발자가 우리 플랫폼에서 작동하는 앱을 만들 수 있도록 개발 가이드를 쓰고, 샘플 앱을 만들고, 세미나를 하거나 고객사에 설명하거나 또는 개인 개발자와 소통했다. 그래서일까, 자연스럽게 기술 문서의 중심은 외부 개발자용 문서라고 생각하게 되었다.물론 내부 기술 문서를 다룰 때도 있었지만, 내게 기술 문서의 꽃은 어디까지나 외부에 제공하는 API 문서와 튜토리얼이었다.</p><p>지금 회사로 옮긴 뒤에도 주 업무는 외부 제공 문서였다. 당시 내 관심사는 문서 작성 방법이어서, 외부용 문서를 쓰기만 하는 게 아니라 <strong>문서를 배포하고 운영하는 것까지 해야겠다</strong>고 생각했다.</p><p>사실 배포 파이프라인 관리나 웹사이트 운영이 테크니컬 라이터의 전통적인 업무라고 하기는 어렵다. 하지만 여기선 내가 그걸 하지 않으면 Docs as Code를 실현하기 어려웠기에 직접 해보고 싶었다. 팀에 개발자가 있다면 개발자가 해주는 편이 편할 수도 있다. 하지만 테크니컬 라이터가 직접 할 수 있다면 문서의 작성부터 빌드, 배포, 운영까지 원하는 대로 흐름을 만들 수 있다는 게 장점이다.</p><p>이때부터 테크니컬 라이터라는 이름만으로는 내가 하는 일을 설명하기 어렵다고 생각했고, <strong>문서 엔지니어</strong>라는 말을 쓰기 시작했다.</p><h3><strong>내부 소통 도구로서의 문서</strong></h3><p>2~3년이 지난 후, 사내 채널에서 제품 팀 간 소통 도구로 외부 기술 문서가 사용되는 걸 봤다. 그도 그럴 것이, 규모가 큰 조직에서는 기획자와 개발자 사이의 소통이 쉽지 않다. 서로 아는 정보가 다르고 정보를 공유받는 시점도 제각각이다. 만약 그 정보 중 문서화 된 게 있다면 적어도 같은 내용을 두고 서로 이야기할 수 있으니 소통에 도움이 되었을 것이다.</p><p>사내 위키에도 문서를 쓰지만, 솔직히 위키는 정확하고 공식적인 정보를 관리하는 용도로는 여러 가지 한계가 있다. 이 부분은 언젠가 따로 써보고 싶다.</p><p>어쨌든 그걸 보며 <strong>내부 소통을 위한 문서가 중요하다</strong>는 걸 깨달았다. 내부에서 소통할 때 사용할 기술 정보가 잘 되어 있다면 그걸 바탕으로 외부 문서를 만드는 것은 비교적 쉽다. 반대로 내부 정보가 엉망이라면 외부 문서를 만드는 일 자체가 중복 작업이 될 수 있고, 잘못된 정보가 들어갈 가능성도 커진다.</p><h3>피드백이 많은 문서</h3><p>테크니컬 라이터에게는 독자의 피드백이 중요하다. 글이 좋은지 나쁜지, 무엇이 부족한지 알려면 실제 독자의 의견이 꼭 필요한데, 아쉽게도 외부 독자는 피드백을 잘 주지 않는다. 플랫폼을 사용하는 사람이 많지 않을 수도 있고, B2B 제품이라 문서보다는 서포트 엔지니어와 직접 소통해 문제를 해결할 때도 있어서다.</p><p>반면 내부 기술 문서는 회사 사람이 모두 보는 데다 소통 창구도 열려 있으니 피드백을 받을 가능성이 훨씬 높다. 물론, 소통을 극도로 꺼리는 엔지니어나 “역시 말로 이야기하는 게 제일 빠르죠”라는 문화가 자리 잡은 조직이라면 내부 문서도 쉽지 않지만. 그래도 일반적으로는 외부 독자보다 내부 독자의 피드백을 받기가 쉬우니, 갓 시작하는 테크니컬 라이터에게는 내부 문서를 맡아 쓰는 게 좋을 수 있다.</p><p>그 시점에 나는 외부 개발자용 문서 중심으로만 생각하던 업무를 <strong>내부 기술 문서</strong>로 확장하게 되었다. 그래서 시작한 일이 바로 사내에서 반드시 사용해야 하는 인프라 플랫폼 문서였다. 내가 문서 엔지니어링을 하면서 자주 접했던 영역이라 관심이 있었던 데다 사내 독자도 많으니까. 그 외에도, 사내 플랫폼 정보 포털을 만드는 일도 맡으며 사내 문서화 업무를 파고들기로 했다.</p><p>당연하지만, 내부 기술 문서 역시 Docs as Code를 적용할 수 있도록, 제품 담당자에게 어필하거나 사내에 세미나도 했다.</p><h3><strong>AI 시대의 기술 문서</strong></h3><p>AI 시대가 되면서 Docs as Code는 개발자들이 선호하는 방식이 되었다. AI 코딩 에이전트가 마크다운으로 문서 산출물을 내놓으니 당연하다. 물론 각종 사내 위키에 배포하거나 위키 문서와 마크다운을 변환하는 기능도 여기저기서 만들며 레거시 시스템을 살리려는 움직임도 있지만, <strong>문서도 개발 프로세스에 포함해서 자동으로 만들자</strong>는 흐름이 왔다는 게 중요하다.</p><p>이렇게 다루는 문서는 대부분 내부 문서로 볼 수 있다. 제품 개발 과정에서 결정된 설계 정보, 사용법, 변경 사항, 운영 정보는 보통 내부 문서에 쓰기 때문이다.</p><p>그러니 Docs as Code 방식을 잘 따라왔다면, AI 시대에 테크니컬 라이터의 역할을 확장해볼 수 있다. 바로 <strong>문서를 만드는 구조를 설계하는 역할</strong>이다. 문서 엔지니어로서 AI 에이전트나 문서 자동화 시스템을 직접 만들 수 있다면 제일 좋겠지만 꼭 시스템을 직접 만들 필요는 없다. <strong>문서 작성 규칙을 만들고, 관리용 메타데이터를 정의하고, 문서 유형별 구조와 템플릿을 만들고, 품질 관리 프로세스를 설계</strong>하는 것도 충분히 중요한 역할이다. 내부 문서를 잘 관리하는 법은 제품팀에서도 고민할 수 있겠지만, 앞서 말한 역할은 테크니컬 라이터가 누구보다 다 잘 할 수 있다.</p><p>이 점은 예전에 쓴 AI 시대 테크니컬 라이터의 길에서 조금 더 자세하게 이야기했다.</p><h3><strong>글쓰기를 놓고 싶지 않다면</strong></h3><p>앞서 말한 설계자로의 역할 전환에는 <strong>글 쓰는 역할을 AI에 맡긴다</strong>는 전제가 깔려있다. 자발적으로든 또는 비자발적으로든 더는 글쓰기로 먹고 살 수 없게 되었을 때를 대비한 것이다.</p><p>그런데 정말 글쓰기를 좋아해서 AI에 그 역할을 양보하고 싶지 않은 사람이라면? 혹시 <strong>자신만의 스타일을 가진 외부 문서</strong>가 답이 될 수 있지 않을까?</p><p>지금도 링크드인이나 블로그를 보면 AI가 쓴 글을 어렵지 않게 발견할 수 있다. 작성자가 말하지 않아도 알아챌 수 있는 이유는, “AI스러운 표현과 스타일” 때문일 터다. 그 “AI스러움을 없애 주는 스킬”도 여기저기 나와 있지만 글쎄.</p><p>그런 글을 보면 “아, 이것도 AI가 썼네…” 하면서 쓱 내리는 건 나뿐일까?</p><p>나 같은 독자가 많다면, 뻔하디 뻔한 AI투로 범벅된 문서를 공개한다는 건 결국 회사 평판에도 좋지 않을 터다. 앞으로 AI가 더 발전해서, 그때그때 다른 개성을 담아 글을 쓰게 될지도 모르지만, 그때가 오기 전에는 외부용 기술 문서에서 <strong>사람의 힘</strong>이 큰 역할을 할지 수도 있다. 내용이 올바르고, 구성이 논리적인지 점검하는 것도 물론 사람이 할 일이지만, 그에 더해 <strong>사람 느낌이 나는 글투, 테크니컬 라이터의 고유한 관점과 스타일</strong>도 의미가 있을 것이다. MP3가 점령한 후에도 LP를 그리워하는 마니아들이 있듯이, 사람마저 AI투를 따라 하게 될 미래(아마 현재도)에 사람 냄새나는 글을 찾는 마니아들이 생겨날지도 모르니까.</p><p>그렇다면, AI 시대 테크니컬 라이터에게는 두 갈래 길이 있다.</p><ul><li><strong>문서 엔지니어링과 AI를 활용해 문서를 만들고 관리하는 시스템을 설계하는 길</strong></li><li><strong>AI가 흉내 내기 어려운 자신만의 스타일을 만드는 길</strong></li></ul><h3><strong>계속 바뀌는 삶</strong></h3><p>돌이켜보면 내 생각은 계속 바뀌었다.</p><p>처음에는 외부 문서가 중요하다고 생각했다. 그다음에는 내부 문서가 더 중요하다고 생각했다. 그리고 지금은 문서 자체보다 <strong>문서를 쓰는 방식 설계</strong>가 더 중요하다고 생각한다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8SDZVuMHk9V1DOPM-h_L6g.png" /></figure><p>변하지 않는 것도 중요하고, 초심을 지키는 것도 중요하다. 하지만 때론 유연함도 필요하다. 21년간 똑같이 생각하고 똑같은 방식으로 일하는 것도 귀한 결과지만, 한편으로는 계속 다른 생각을 하고 방향을 바꾸는 것도 가치가 있다고 생각한다.</p><p>그간 내가 걸어온 길에는 딱 정해진 커리어 목표가 없었다. 목표보다는, <strong>내가 무엇을 좋아하는지, 어떤 환경에서 재미있게 일하는지 알아내고 그 방식을 추구해 온 길</strong>에 가깝다. 나는 특정한 일 하나를 찾아 꾸준히 해낼 성격은 못 되는 것 같다. 새로운 걸 해 보고, 하던 방식을 바꾸고, 일의 방향을 틀어가면서 즐거움을 찾는 쪽이랄까.</p><p>앞으로도 내 생각은 바뀔 것이다. 어쩌면 안정적인 회사를 다시 그리워할지도 모르지만, 그 역시 변화로 볼 수 있겠지.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aaf2267005db" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Writing for AI]]></title>
            <link>https://lyingdragon.medium.com/writing-for-ai-caab3344f279?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/caab3344f279</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[technical-writing]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Fri, 13 Feb 2026 12:03:34 GMT</pubDate>
            <atom:updated>2026-02-13T12:03:34.725Z</atom:updated>
            <content:encoded><![CDATA[<p>Writing Guide for LLM and RAG</p><p>“How should I write so that AI can read documents well?”</p><p>This is a question I hear frequently these days. It’s likely because various attempts are being made in multiple places to create GPTs, integrate conversational AI with Google Drive, use NotebookLM, and even construct RAG systems to enhance searchability.</p><p>The fundamental principle of technical writing is <strong>reader empathy</strong>. The goal is to write information that readers want in a way that readers can understand. Given these questions, it seems AI has now become a major reader of technical documents. If so, writing information that AI wants in a way AI can understand would also be technical writing.</p><h3>Audience Analysis First</h3><p>Let’s first examine what characteristics the new reader “AI” has. When writing technical documents, we’re often told to “write simply, assuming the reader knows nothing,” but this reader absolutely doesn’t know nothing. It has the highest level of technical knowledge and language abilities. However, depending on the approach used, it sometimes reads documents slightly differently than humans do.</p><h4>When Providing Directly to LLM</h4><p>When you provide an entire technical document directly to an LLM, it’s similar to when humans read it. However, it can be slightly different depending on the situation.</p><ul><li><strong>Pasting entire text into Chat-type AI</strong>: If it doesn’t exceed the context window per model, it reads everything and responds. It’s similar to humans. However, if it exceeds the context window, it reads in parts or extracts only appropriate sections, so it cannot grasp the overall context.</li><li><strong>Registering as reference material in GPTs</strong>: It only finds and reads parts needed for user questions. This means that just because you registered 10 files doesn’t mean it reads all 10.</li><li><strong>Requesting Google Drive file search in Chat-type AI</strong>: After primary filtering according to Google Drive’s search strategy, it retrieves appropriate documents. If the document size doesn’t exceed the context window, it reads everything and responds. Otherwise, it reads in parts or extracts only appropriate sections.</li><li><strong>Registering documents in NotebookLM</strong>: It reads all registered documents. It’s almost the same as humans reading.<br>Assuming it doesn’t exceed the context window, because it reads the entire document and responds, it’s easy to grasp the context and can combine overall comparisons or information located far apart. Let’s call this situation the “long context method” here.</li></ul><p>If you plan to give your written document to AI using the long context method, it’s also effective with general technical document writing techniques for human readers.</p><h4>When Using RAG</h4><p>When using RAG, your written document isn’t delivered to the LLM in its entirety, but only parts suitable for user queries are extracted and delivered. This is similar to the situation of “registering as reference material in GPTs” mentioned earlier.</p><p>RAG typically calculates and stores embedding values of target chunks, then when there’s a query, it finds N chunks similar to the query’s embedding value and delivers them to the LLM along with the query. Therefore, while the actual content is related to the query, if for various reasons the embedding vector is far from the query or there’s too much miscellaneous similar information preventing it from making the Top-N, the search fails.</p><p>If you plan to give your written document to AI using the RAG method, there are more points to consider. You need to understand well the chunking strategy, search strategy, and other supporting features of the RAG you’ll apply.</p><p>In this post, we’ll consider both methods, but particularly address <strong>AI-friendly writing</strong> methods that can be applied when using RAG.</p><h3>Technical Writing: The Most Solid Foundation for AI</h3><p>Interestingly, writing that’s good for AI reading aligns very well with several technical writing techniques. This is because AI likes logical, structured information and clear expressions. Thanks to this, commonly mentioned ‘good writing methods’ are also effective in improving AI readability.</p><ul><li><strong>Complete structure</strong>: Write heading levels (H1, H2, H3…) in order</li><li><strong>Clear logic</strong>: Organize content so it doesn’t duplicate or miss anything</li><li><strong>Conciseness</strong>: Include only one fact per sentence and avoid rhetoric as much as possible</li></ul><p>In other words, “<strong>following technical writing principles well provides the foundation for AI-friendly documents.</strong>” Whether it’s the long context method or RAG, it’s good to apply the above techniques as a baseline.</p><h3>Adding Writing Principles for AI</h3><p>Now let’s add AI-friendly writing principles considering RAG.</p><ul><li><strong>Maintain context independence</strong>: When text is cut into chunking units, make it possible to understand the meaning from that piece alone without looking at surrounding content.</li><li><strong>Consider vector values</strong>: Eliminate ambiguous instructions so embedding coordinates don’t scatter.</li><li><strong>Separate AI documents</strong>: If possible, separate documents for humans and AI. Like how llms.txt points to markdown format documents that are good for AI bots to read.</li></ul><p>Regarding the third principle, I’ll elaborate more at the end of this post.</p><h3>Write in Markdown</h3><p>Before proposing AI-friendly writing methods based on the above principles, let’s talk about format first.</p><p>When creating technical documents to give to AI, Markdown format is good. While well-known MS Word, PDF, and HTML are also read well, they have much information unrelated to content like tags and can lose context in page breaks. Moreover, if you’re building RAG directly, you need to preprocess to extract necessary information from files configured at the author’s discretion.</p><p>LLMs have learned many documents written in Markdown, so they’re proficient with Markdown. Additionally, Markdown has the advantage of simple syntax that makes anyone write similarly.</p><p>The reason llms.txt provides original Markdown file addresses is also because Markdown is clearer for LLMs to understand.</p><p>If you can’t write in Markdown, <strong>it’s better to create templates so authors write according to templates</strong> without changing them arbitrarily.</p><h3>Practical! Writing Rules for AI</h3><p>Now I’ll organize writing rules that work well with AI.</p><h4>Minimize Use of Demonstratives/Pronouns</h4><p>RAG processes long documents by chunking them into predetermined units. Therefore, to help AI understand content just by looking at text fragments and to make embedding values similar to query terms, it’s better not to use ambiguous demonstratives like ‘this’, ‘mentioned above’, or ‘that setting’. (This may vary depending on chunking strategy, but it’s better to apply it anyway)</p><blockquote>❌ When the problem mentioned above occurs, delete the data. (Don’t know which problem)</blockquote><blockquote>🟢 When data integrity errors occur, delete the data. (Can be found by searching for ‘data integrity’)</blockquote><h4>Write Proper Nouns in Full Names</h4><p>People like concise writing, so they often attach abbreviations to proper nouns. Technical writers, knowing this, sometimes specify abbreviations at the beginning and use abbreviations throughout the document. Here’s an example.</p><blockquote>The Gathering People (hereinafter GPle) service matches people in the same interest areas among those physically nearby.</blockquote><blockquote>…</blockquote><blockquote>❌ The GPle service provides the following interfaces for convenient developer adoption:<br>- GPle developer console<br>- GPle sandbox</blockquote><blockquote>🟢 The Gathering People service provides the following interfaces for convenient developer adoption:<br>- Gathering People developer console<br>- Gathering People sandbox</blockquote><p>People or LLMs reading documents from the beginning understand that Gathering People = GPle by seeing ‘hereinafter GPle’, but in RAG, the embedding values of “Gathering People” and “GPle” may be distant, making it difficult to find answers to questions like “What’s the developer console address for Gathering People?”</p><p>You could build RAG to process by providing information that two words have the same meaning in advance. Otherwise, don’t define abbreviations and always write in full names. If users also use abbreviations frequently, it’s better to use both full names and abbreviations together. (Google Vertex AI and others reportedly solved this problem with synonym registration features. If such features exist, register as synonyms rather than repeating full names and abbreviations unnecessarily.)</p><h4>Use Descriptive Headings</h4><p>Descriptive headings that fully explain content are more favorable for AI than short, concise headings. Also, as depth increases, it’s better to include parent headings.</p><blockquote>❌ ## Overview, ## Precautions, ## Settings (Unclear what the overview is for)</blockquote><blockquote>🟢 ## Payment Module Integration Guide Overview, ## Precautions When Calling APIs</blockquote><p>If there’s only one product document in RAG, this won’t be a problem, but otherwise, it’s difficult to know which product’s ‘overview’ among multiple products. It’s better to give appropriate headings to products.</p><h4>Give Meaning to File Names</h4><p>File names are important metadata that determine search ranking and reliability. Especially when uploading to Google Drive and delivering to LLMs, you need to name files well for good matching in Google Drive search. Even if you’ve entered the full product name in the parent folder name, it’s safer to enter the product name in the file name as well.</p><blockquote>❌ Meeting notes.md (too common)</blockquote><blockquote>🟢 2026–01-Backend-Team-Meeting-Notes.md</blockquote><blockquote>❌ Architecture.md (don’t know whose architecture)</blockquote><blockquote>🟢 Billing-System-Microservice-Architecture.md</blockquote><h4>Provide Text Descriptions for Images</h4><p>RAG (Retrieval-Augmented Generation) is inherently weak at processing non-text information. If you explain key concepts only through images, the system might fail to retrieve that information for users. Always include captions or text descriptions.</p><p>If your goal is to let the system know, “Show this image when a user asks for X,” then adding a caption is the way to go.</p><blockquote>❌ ![](images/payment-process.png) (Without text, the context is lost.)</blockquote><blockquote>🟢 ![Payment approval process flowchart: User request -&gt; PG approval -&gt; Merchant notification](images/payment-process.png)</blockquote><p>Pro Tip: Use Explicit Text</p><p>Keep in mind that some RAG pipelines might ignore Markdown image syntax entirely. It’s often better to include an explicit text description alongside the image – especially if the content is too complex for a single caption or contains information users search for frequently.</p><blockquote>🟢 ![Payment approval process flowchart: User request -&gt; PG approval -&gt; Merchant notification](images/payment-process.png)</blockquote><blockquote>The image above illustrates the payment approval flowchart. When a user initiates a payment, the PG (Payment Gateway) approves it, and a completion notification is sent to the merchant. In section A of the diagram…</blockquote><h4>Simplify Your Tables</h4><p>If you rely heavily on tables, you need to be extra careful in the age of AI. While tables are great for human eyes, they aren’t always AI-friendly. Especially when creating large, complex tables in tools like MS Word, RAG systems often struggle to process them correctly during the “chunking” phase.</p><p>You don’t have to ditch tables entirely, but try to stick to these essential rules:</p><ul><li><strong>No Merged Cells</strong>: Merged cells are the #1 cause of parsing errors. Avoid them at all costs.</li><li><strong>No Nested Tables</strong>: Putting a table inside another table makes an already complex structure nearly impossible for AI to analyze.</li><li><strong>Stick to Markdown over HTML</strong>: While some use HTML to handle complex layouts, it’s better to stick with standard Markdown syntax. AI models handle simple Markdown tables much more reliably.</li><li><strong>Use Bullet Points Instead</strong>: If a table becomes too cramped (e.g., multiple lines of text inside a single cell), consider breaking that information out into a clear, bulleted list instead.</li></ul><blockquote>❌</blockquote><blockquote>| Service A | Service B |</blockquote><blockquote>| – -| – -|</blockquote><blockquote>| Quisque non egestas orci. In a imperdiet nunc. Aenean eget pharetra augue. Maecenas hendrerit leo mauris, ut faucibus urna suscipit ac. Etiam auctor, ante in tincidunt lacinia, urna urna maximus orci, vel finibus felis nibh eu ipsum. Duis eu erat imperdiet, pulvinar tortor sed, bibendum lorem. Vestibulum ultrices sapien a magna vulputate scelerisque. Morbi libero magna, elementum non ex non, mattis congue arcu. Cras eget blandit enim, in eleifend arcu. Proin id leo diam. Donec eget eleifend nisi. Pellentesque nec massa sagittis, faucibus lectus sit amet, volutpat tortor. Pellentesque nec aliquet mauris. Cras accumsan justo massa, nec tempus neque facilisis eu. &lt;br/&gt; Nam ullamcorper maximus sagittis. Phasellus eros lorem, posuere in nisl at, maximus mollis purus. Ut suscipit velit risus, eu mollis nunc bibendum et. Duis vehicula libero volutpat, posuere ex hendrerit, suscipit mauris. Quisque risus quam, mollis vel ante suscipit, rutrum vehicula sem. Suspendisse interdum in nulla a ornare. Nulla fermentum efficitur mauris sed tempor. Mauris eu massa accumsan, luctus enim nec, dictum justo. In non tortor id elit ullamcorper maximus quis ac arcu. Aliquam vulputate auctor metus, a elementum tortor blandit sed. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Cras vulputate suscipit lobortis | Quisque non egestas orci. In a imperdiet nunc. Aenean eget pharetra augue. Maecenas hendrerit leo mauris, ut faucibus urna suscipit ac. Etiam auctor, ante in tincidunt lacinia, urna urna maximus orci, vel finibus felis nibh eu ipsum. Duis eu erat imperdiet, pulvinar tortor sed, bibendum lorem. Vestibulum ultrices sapien a magna vulputate scelerisque. Morbi libero magna, elementum non ex non, mattis congue arcu. Cras eget blandit enim, in eleifend arcu. Proin id leo diam. Donec eget eleifend nisi. Pellentesque nec massa sagittis, faucibus lectus sit amet, volutpat tortor. Pellentesque nec aliquet mauris. Cras accumsan justo massa, nec tempus neque facilisis eu. |</blockquote><blockquote>🟢</blockquote><blockquote>- Service A</blockquote><blockquote>~~~</blockquote><blockquote>- Service B</blockquote><blockquote>~~~</blockquote><h3>Does This Really Help?</h3><p>I briefly measured whether these rules really help. The test involved writing short documents of a few lines, then inputting them to LLM as long context to ask questions, and configuring them as RAG to ask questions. For RAG, I tested separately when putting in entire documents without chunking, when chunking by paragraphs (heading sections), when chunking by sentences (separated by periods), and when chunking by fixed character count. (Images, tables, and file names were excluded from testing)</p><ul><li><strong>Minimize use of demonstratives/pronouns</strong>: Effects varied depending on RAG chunking strategy. When inputting entirely, searchability actually decreased, but it helped when using sentence-level chunking.</li><li><strong>Use descriptive headings</strong>: Notable effects appeared in both LLM and RAG. Especially significant effects were seen in RAG.</li><li><strong>Write proper nouns in full names</strong>: Not a huge difference, but effects appeared in RAG chunking strategies that don’t input entirely.</li></ul><p>While the conclusions are limited because very short documents were tested to check effectiveness, we could see that effects do appear. (Actually, there are rules that were removed from the post due to test results haha) To see how meaningful the effects are, we’d need to test with longer and more diverse documents, which I plan to organize into writing when ready.</p><h3>Human-First, Machine-Native</h3><p>Following these rules might raise this question:</p><p>“Continuously repeating subjects, not using tables, writing long headings… Isn’t this too tiresome for humans to read?”</p><p>Certainly, there is conflict between writing that’s good for humans to read and writing that’s good for AI to read. The most ideal solution is <strong>to separate the ‘rendering screen that humans see’ from the ‘original data (metadata) that AI reads’</strong>.</p><p>But if you need to write documents that are good for AI to read without such systems, try adopting the mindset of “<strong>writing kindly and in detail.</strong>” Writing that’s kind to AI will ultimately become clear, unambiguous, good documents for humans to read too.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=caab3344f279" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI를 위한 글 쓰는 법]]></title>
            <link>https://lyingdragon.medium.com/ai%EB%A5%BC-%EC%9C%84%ED%95%9C-%EA%B8%80-%EC%93%B0%EB%8A%94-%EB%B2%95-da2856dee6e1?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/da2856dee6e1</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[technical-writing]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sun, 08 Feb 2026 13:04:53 GMT</pubDate>
            <atom:updated>2026-02-13T12:04:45.990Z</atom:updated>
            <content:encoded><![CDATA[<p>“AI가 문서를 잘 읽을 수 있게 하려면 어떻게 써야 하나요?”</p><p>요즘 자주 듣는 질문입니다. GPTs, 대화형 AI와 Google Drive 연동, NotebookLM, 나아가 RAG을 구축해 검색성을 높이려는 시도가 여러 곳에서 벌어지기 때문이겠죠.</p><p>테크니컬 라이팅의 기본 원칙은 <strong>독자 공감</strong>입니다. 독자가 원하는 정보를, 독자가 알아들을 수 있는 글로 쓰는 게 목적이란 말이죠. 이런 질문이 오는 걸 보면, 이제는 AI가 기술 문서의 주요 독자가 되었나 봅니다. 그렇다면, AI가 원하는 정보를 AI가 알아들을 수 있도록 쓰는 일 역시 테크니컬 라이팅이 되겠네요.</p><blockquote><a href="https://lyingdragon.medium.com/writing-for-ai-caab3344f279">English version</a></blockquote><h3>독자 분석 먼저</h3><p>우선 새로운 독자인 “AI”는 어떤 특징이 있는지 살펴봅시다. 기술 문서를 쓸 때는 “독자가 아무것도 모른다고 생각하고 쉽게 쓰라”고들 하는데요, 이 독자는 절대 아무것도 모르지 않습니다. 최고 수준의 기술 지식과 언어 능력을 가졌죠. 다만, 어떤 방식을 쓰느냐에 따라 사람과는 약간 다르게 문서를 읽을 때가 있습니다.</p><h4>LLM에 직접 제공할 때</h4><p>기술 문서 전체를 LLM에 직접 제공하면, 사람이 읽을 때와 비슷합니다. 다만 상황에 따라 살짝 다를 수 있습니다.</p><ul><li><strong>Chat형 AI에 전체 텍스트를 붙여 넣기</strong>: 모델별 context window를 넘지 않는다면 전부 읽고 대답합니다. 사람과 비슷하죠. 다만, Context window를 넘으면 나눠서 읽거나 적절한 부분만 추출하기 때문에 전체 맥락을 파악하지 못합니다.</li><li><strong>GPTs에 참고 자료로 등록</strong>: 사용자 질문에 필요한 부분만 찾아서 읽습니다. 즉 파일 10개를 등록했다고 해서 10개를 다 읽지 않습니다.</li><li><strong>Chat형 AI에 Google Drive 파일 검색 요청</strong>: Google Drive의 검색 전략에 따라 1차 필터링한 다음 알맞은 문서를 읽어오는데, 문서 크기가 context window를 넘지 않으면 전부 읽고 대답합니다. 그렇지 않다면 나눠서 읽거나 적절한 부분만 추출합니다.</li><li><strong>NotebookLM에 문서 등록</strong>: 등록한 문서를 다 읽습니다. 사람이 읽는 것과 거의 같습니다.</li></ul><p>Context window를 넘기지 않는다는 가정하에, 문서를 전부 읽고 대답하기 때문에 맥락을 파악하기 쉽고, 전체 비교 또는 한참 떨어진 곳에 있는 정보를 조합할 수 있습니다. 여기서는 이런 상황을 “long context 방식”이라고 부르기로 합시다.</p><p>작성한 문서를 long context 방식으로 AI에 줄 계획이라면, 일반적으로 사람 독자를 위한 기술 문서 작성 기법으로도 효과적입니다.</p><h4>RAG을 사용할 때</h4><p>RAG을 사용하면 작성한 문서가 통째로 LLM에 전달되는 게 아니라, 사용자 질의에 알맞은 부분만 추출해서 전달됩니다. 앞서 “GPTs에 참고 자료로 등록”한 상황과 비슷합니다.</p><p>RAG은 보통 대상 청크의 임베딩값을 계산해서 저장해 뒀다가, 질의가 있으면 그 질의문의 임베딩값과 비슷한 청크를 N개 찾아서 질의와 함께 LLM에 전달합니다. 따라서, 실제 내용은 질의와 연관되지만, 이런저런 이유로 임베딩 벡터가 질의문과 많이 떨어져 있거나 다른 잡다한 유사 정보가 많아서 Top-N에 들지 못한다면 검색에 실패합니다.</p><p>작성한 문서를 RAG 방식으로 AI에 줄 계획이라면, 고려할 점이 좀 더 많습니다. 적용할 RAG의 청킹 전략, 검색 전략, 기타 지원 기능을 잘 파악해야 하니까요.</p><p>이 포스트에서는 두 방식을 모두 고려하되, 특히 RAG를 사용할 때 적용할 만한 <strong>AI 친화적인 글쓰기</strong> 방법을 다뤄보겠습니다.</p><h3>테크니컬 라이팅: AI를 위한 가장 확실한 기초</h3><p>재미있게도, AI가 읽기 좋은 글은 <strong>테크니컬 라이팅 기법 몇 가지</strong>와 아주 잘 맞아떨어집니다. AI는 논리적이고 구조화된 정보와 명확한 표현을 좋아하기 때문이죠. 덕분에 흔히 말하는 ‘글을 잘 쓰는 방법’은 AI의 가독성을 높이는 데도 효과적입니다.</p><ul><li><strong>완전한 구조:</strong> 제목 수준(H1, H2, H3…)은 순서대로 쓰기</li><li><strong>명확한 논리</strong>: 내용이 중복되거나 빠지지 않도록 구성하기</li><li><strong>간결성:</strong> 한 문장에는 한 가지 사실만 입력하고, 수사는 되도록 피하기</li></ul><p>말하자면, <strong>“테크니컬 라이팅 원칙만 잘 지켜도 AI 친화적인 문서”</strong>의 기본을 갖췄다고 볼 수 있습니다. Long context 방식이든 RAG든 위 기법은 기본으로 적용하는 편이 좋습니다.</p><h3>AI를 위한 글쓰기 원칙 더하기</h3><p>이제 RAG을 고려한 AI 친화적 글쓰기 원칙을 더합시다.</p><ul><li><strong>맥락 독립 유지:</strong> 글을 청킹 단위로 잘라냈을 때, 앞뒤 내용을 보지 않고도 그 조각만으로 의미를 알 수 있게 합니다.</li><li><strong>벡터값 고려:</strong> 모호한 지시를 없애 임베딩 좌표가 흩어지지 않게 합니다.</li><li><strong>AI용 문서 분리:</strong> 가능하다면 사람용과 AI용 문서를 분리합니다. llms.txt에서 AI봇이 읽기 좋은 markdown 포맷 문서를 가리키는 것처럼요.</li></ul><p>세 번째에 원칙에 관해서는 이 포스트 마지막에 좀 더 부연하겠습니다.</p><h3>Markdown으로 쓰세요</h3><p>위의 원칙에 따라 AI 친화적 글쓰기 방법을 제안하기 전에, 포맷부터 이야기해 봅시다.</p><p>AI에게 줄 기술 문서를 작성할 때는 Markdown 포맷이 좋습니다. 잘 알려진 MS Word, PDF, HTML도 잘 읽긴 하지만, 태그 등 내용과 무관한 정보가 많고 페이지 나눔에서 맥락을 잃어버릴 수 있습니다. 게다가 직접 RAG을 구축한다면, 작성자 마음대로 구성한 파일에서 필요한 정보를 빼내는 전처리까지 해야 합니다.</p><p>LLM은 Markdown으로 작성한 문서를 많이 학습했으므로 Markdown에 능숙합니다. 게다가 Markdown은 문법이 단순해서 누가 써도 비슷하게 쓰게 되는 장점이 있습니다.</p><p>llms.txt에서 원본 Markdown 파일 주소를 제공하는 이유도 Markdown이 LLM이 이해하기에 좀 더 분명하기 때문입니다.</p><p>만약 markdown으로 쓸 수 없는 상황이라면, <strong>템플릿을 만들어 작성자가 함부로 바꾸지 않고 템플릿에 맞춰 쓰도록 하는 편이 좋습니다</strong>.</p><h3>실전! AI를 위한 글 작성 규칙</h3><p>이제 AI에 잘 통하는 글 작성 규칙을 정리하겠습니다.</p><h4>지시어/대명사 사용 자제</h4><p>RAG는 긴 문서를 정해진 단위로 청킹(chunking)해서 처리합니다. 따라서 글 조각만 보고도 AI가 내용을 이해하도록, 또 임베딩 값이 질의어와 비슷하게 나올 수 있도록, ‘이것&#39;, ‘위에서 말한&#39;, ‘그 설정&#39; 같은 모호한 지시어는 쓰지 않는 것이 좋습니다. (청킹 전략에 따라 달라질 수 있지만 이왕이면 적용하는 게 좋습니다)</p><blockquote>❌ <em>위에서 말한 문제가 발생하면 데이터를 삭제합니다.</em> (어떤 문제인지 모름)</blockquote><blockquote>🟢 <em>데이터 정합성 오류가 발생하면 데이터를 삭제합니다. (‘데이터 정합성’으로 검색하면 발견 가능)</em></blockquote><h4><strong>고유 명사는 풀네임으로 작성</strong></h4><p>사람은 간략한 글을 좋아해서 고유 명사에 곧잘 약어를 붙입니다. 테크니컬 라이터도 이를 알기에 글 첫머리에 약어를 명시하고 문서 전체에 약어를 쓸 때가 있습니다. 아래가 그 에시입니다.</p><blockquote>Gethering People (이하 GPle) 서비스는 물리적으로 가까운 곳에 있는 사람 중 같은 관심 분야를 가진 이를 매칭해 줍니다.</blockquote><blockquote>…</blockquote><blockquote>❌ GPle 서비스는 개발자가 편리하게 도입할 수 있도록 다음과 같은 인터페이스를 제공합니다.<br>- GPle 개발자 콘솔<br>- GPle 샌드박스</blockquote><blockquote>🟢 Gethering People 서비스는 개발자가 편리하게 도입할 수 있도록 다음과 같은 인터페이스를 제공합니다.<br>- Gethering People 개발자 콘솔<br>- Gethering People 샌드박스</blockquote><p>처음부터 문서를 읽는 사람이나 LLM은 ‘이하 GPle’을 보고 Gethering Peope = GPle 임을 이해하지만, RAG에서는 “Gathering People”과 “GPle”의 임베딩 값이 멀어져 “Gatherping People의 개발자 콘솔 주소가 뭐야”라는 질문을 찾아내기 어려울 수 있습니다.</p><p>미리 두 단어가 같은 의미라는 정보를 주고 처리하도록 RAG을 구축할 수도 있습니다. 그렇지 않다면, 약어를 정의하지 말고 항상 풀네임으로 작성하세요. 만약 사용자들이 약어도 많이 쓴다면, 풀네임과 약어를 함께 쓰는 편이 좋습니다. (Google Vertex AI 등에서는 유사어 등록 기능으로 이런 문제를 해결했다고 합니다. 그런 기능이 있다면 구태여 풀네임과 약어를 반복할 필요 없이 유사어로 등록하세요.)</p><h4>제목(Heading)은 서술형으로</h4><p>짧고 간결한 제목보다는 내용을 충분히 설명하는 <strong>서술형 제목</strong>이 AI에 유리합니다. 또한, 깊이가 깊어질수록 부모 제목을 포함하는 것이 좋습니다.</p><blockquote>❌## 개요, ## 주의사항, ## 설정 (어떤 대상의 개요인지 불명확)</blockquote><blockquote>🟢## 결제 모듈 연동 가이드 개요, ## API 호출 시 주의사항</blockquote><p>RAG에 단 하나의 제품 문서만 있다면 문제가 되지 않지만, 그렇지 않다면 여러 제품 중 어느 제품의 ‘개요&#39;인지 알기 어렵습니다. 이왕이면 제품에 적절한 제목을 붙여주세요.</p><h4>파일명에도 의미를</h4><p>파일명은 검색 랭킹과 신뢰도를 결정하는 중요한 메타데이터입니다. 특히 Google Drive에 업로드해서 LLM에 전달하면, 파일명을 잘 지어야 Google Drive 검색에서 잘 매치됩니다. 상위 폴더 이름에 전체 제품명을 입력했더라도, 파일명에도 똑같이 제품명을 입력하는 편이 좀 더 안전합니다.</p><blockquote>❌ <em>Meeting notes.md</em> (너무 흔함)</blockquote><blockquote>🟢 <em>2026–01-Backend-Team-Meeting-Notes.md</em></blockquote><blockquote>❌ <em>Architecture.md </em>(누구의 아키텍처인지 모름)</blockquote><blockquote>🟢 <em>Billing-System-Microservice-Architecture.md</em></blockquote><h4>이미지에 텍스트 정보 제공</h4><p>RAG는 텍스트 외의 정보에 취약합니다. 중요한 정보를 이미지로 설명하면 사용자가 검색하지 못할 수도 있으니 캡션이나 텍스트 설명을 추가하세요.</p><p>“사용자가 이런 정보를 원하면 이 그림을 보여주세요.”라는 의미라면 이미지에 캡션을 넣으면 됩니다.</p><blockquote>❌ ![](images/payment-process.png) <em>(이미지만 있으면 맥락에서 사라짐)</em></blockquote><blockquote>🟢 ![결제 승인 프로세스 흐름도: 사용자 요청 -&gt; PG사 승인 -&gt; 가맹점 노티](images/payment-process.png)</blockquote><p>다만, RAG을 구축할 때 Markdown의 이미지 문법을 무시하기도 하므로, 이왕이면 명시적인 텍스트로 작성하는 것도 좋습니다. 이미지에 담긴 내용이 캡션 한 줄로 설명하기 어렵거나, 사용자가 자주 검색할만한 정보라면 더욱 그렇습니다.</p><blockquote>🟢 ![결제 승인 프로세스 흐름도: 사용자 요청 -&gt; PG사 승인 -&gt; 가맹점 노티](images/payment-process.png)</blockquote><blockquote>위 이미지는 결제 승인 프로세스 흐름도를 보여줍니다. 사용자가 결제를 요청하면, PG사가 승인하고, 그후 가맹점으로 결제 완료 요청을 전달합니다. 그림의 A 부분에서~~~</blockquote><h4>표 간략화</h4><p>표를 많이 쓰는 분들은 특히 AI 시대에 조심해야 합니다. 표는 사람이 보기에는 좋지만, AI에게는 그다지 좋지 않습니다. 특히 MS Word 등으로 표를 작성하다 보면 몹시 방대하고 복잡한 정보를 담게 되는데, RAG의 청킹 전략에 따라 제대로 처리하지 못할 때가 있습니다.</p><p>표를 아예 쓰지 않을 순 없지만 적어도 아래 규칙은 지키세요.</p><ul><li><strong>셀 병합 금지</strong>: 셀 병합은 파싱 오류의 주범입니다. 절대로 쓰지 마세요.</li><li><strong>표 안의 표 금지</strong>: 표 안의 표는 안 그래도 복잡한 표 분석을 더욱 복잡하게 만듭니다.</li><li><strong>HTML 보다는 Markdown 문법 사용</strong>: Markdown에서 복잡한 표를 사용하려고 HTML을 쓰기도 하는데, 이왕이면 Markdown 문법을 사용하세요. AI도 단순한 Markdown 표는 잘 읽습니다.</li><li><strong>점목록 활용</strong>: 셀 하나에 여러 줄을 입력하는 등의 복잡한 표는 차라리 점목록으로 풀어쓰세요.</li></ul><blockquote>❌ <br>| Service A | Service B |<br>|---|---|<br>| Quisque non egestas orci. In a imperdiet nunc. Aenean eget pharetra augue. Maecenas hendrerit leo mauris, ut faucibus urna suscipit ac. Etiam auctor, ante in tincidunt lacinia, urna urna maximus orci, vel finibus felis nibh eu ipsum. Duis eu erat imperdiet, pulvinar tortor sed, bibendum lorem. Vestibulum ultrices sapien a magna vulputate scelerisque. Morbi libero magna, elementum non ex non, mattis congue arcu. Cras eget blandit enim, in eleifend arcu. Proin id leo diam. Donec eget eleifend nisi. Pellentesque nec massa sagittis, faucibus lectus sit amet, volutpat tortor. Pellentesque nec aliquet mauris. Cras accumsan justo massa, nec tempus neque facilisis eu. &lt;br/&gt; Nam ullamcorper maximus sagittis. Phasellus eros lorem, posuere in nisl at, maximus mollis purus. Ut suscipit velit risus, eu mollis nunc bibendum et. Duis vehicula libero volutpat, posuere ex hendrerit, suscipit mauris. Quisque risus quam, mollis vel ante suscipit, rutrum vehicula sem. Suspendisse interdum in nulla a ornare. Nulla fermentum efficitur mauris sed tempor. Mauris eu massa accumsan, luctus enim nec, dictum justo. In non tortor id elit ullamcorper maximus quis ac arcu. Aliquam vulputate auctor metus, a elementum tortor blandit sed. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Cras vulputate suscipit lobortis | Quisque non egestas orci. In a imperdiet nunc. Aenean eget pharetra augue. Maecenas hendrerit leo mauris, ut faucibus urna suscipit ac. Etiam auctor, ante in tincidunt lacinia, urna urna maximus orci, vel finibus felis nibh eu ipsum. Duis eu erat imperdiet, pulvinar tortor sed, bibendum lorem. Vestibulum ultrices sapien a magna vulputate scelerisque. Morbi libero magna, elementum non ex non, mattis congue arcu. Cras eget blandit enim, in eleifend arcu. Proin id leo diam. Donec eget eleifend nisi. Pellentesque nec massa sagittis, faucibus lectus sit amet, volutpat tortor. Pellentesque nec aliquet mauris. Cras accumsan justo massa, nec tempus neque facilisis eu. |</blockquote><blockquote>🟢<br>- Service A<br> ~~~<br>- Service B<br> ~~~</blockquote><h3>정말 도움이 될까?</h3><p>이런 규칙이 정말 도움이 되는지 간략히 측정해 봤습니다. 몇 줄짜리 짤막한 문서를 작성한 후 LLM에 long context로 입력해서 질문하고, RAG으로 구성해서 질문하는 테스트였습니다. RAG은 청킹 없이 전체 문서를 넣었을 때와 문단(heading 섹션)으로 청킹할 때, 문장(마침표로 구분)으로 청킹할 때, 고정 글자 수로 청킹할 때를 구분해서 테스트했습니다. (이미지와 표, 파일명은 테스트에서 제외했습니다)</p><ul><li><strong>지시어/대명사 사용 자제</strong>: RAG 청킹 전략에 따라 효과가 달랐습니다. 통째로 입력할 때는 오히려 검색성이 떨어졌고, 문장 단위 청킹을 사용할 때 도움이 되었습니다.</li><li><strong>제목은 서술형으로</strong>: LLM과 RAG 모두에서 눈에 띄게 효과가 나타났습니다. 특히 RAG에서 큰 효과를 보였습니다.</li><li><strong>고유 명사는 풀 네임으로: </strong>아주 큰 차이는 아니지만, 통째로 입력하지 않는 RAG 청킹 전략에서 효과가 나타났습니다.</li></ul><p>효과 여부를 확인하기 위해 아주 짧은 문서를 테스트했기에 한계가 있는 결론이지만, 그래도 효과가 나타난다는 것을 알 수 있었습니다. (사실은 테스트 결과로 인해 포스트에서 빠진 규칙도 있습니다ㅎㅎ) 얼마나 유의미한 효과가 있는지는 좀 더 길고 다양한 문서로 테스트해야 할 텐데요, 준비가 되면 글로 정리하려고 합니다.</p><h3>Human-First, Machine-Native</h3><p>이 규칙을 따르다 보면 이런 의문이 들 수 있습니다.</p><p><em>“주어를 계속 반복하고, 표도 쓰지 말고, 제목을 길게 쓰라니… 사람이 읽기엔 너무 피곤하지 않나요?”</em></p><p>확실히, 사람이 읽기 좋은 글과 AI가 읽기 좋은 글에는 충돌이 있습니다.. 가장 이상적인 해결책은 <strong>‘사람이 보는 렌더링 화면’과 ‘AI가 읽는 원본 데이터(메타데이터)’를 분리</strong>하는 것입니다.</p><p>하지만 이런 시스템 없이 우선 AI가 읽기 좋은 문서를 작성해야 한다면, “<strong>친절하고 상세하게 쓴다</strong>”는 마음가짐을 가져보세요. AI에 친절한 글은, 결국 사람이 읽기에도 명확하고 오해 없는 좋은 문서가 될 테니까요.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=da2856dee6e1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Path for Technical Writers in the AI Era]]></title>
            <link>https://lyingdragon.medium.com/the-path-for-technical-writers-in-the-ai-era-7def1e1bf900?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/7def1e1bf900</guid>
            <category><![CDATA[discussion]]></category>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Mon, 19 Jan 2026 08:40:19 GMT</pubDate>
            <atom:updated>2026-01-19T08:40:19.490Z</atom:updated>
            <content:encoded><![CDATA[<p>English version of <a href="https://medium.com/@lyingdragon/ai%EC%8B%9C%EB%8C%80-%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%84%B0%EC%9D%98-%EA%B8%B8-0f460fb192e0">this story</a></p><p>If we’re living in an age where AI does the writing, what exactly is a technical writer supposed to do? What if “writing good technical docs” is no longer enough? Following up on my last post, I want to organize my thoughts on where technical writers should be heading in the AI era.</p><p><a href="https://lyingdragon.medium.com/will-ai-replace-my-job-9d782f7f7b48">Will AI Replace My Job?</a></p><p>Along with my previous post, it would be good to refer to the video I mentioned back then: <a href="https://youtu.be/X9Dzu7nltUg?si=ZwUXY1AV8IaHNOTg"><em>How AI is changing the role of technical writers to “context curators” and “content directors.”</em></a></p><p>In my last post, I proposed three paths:</p><ul><li><strong>Document Engineer:</strong> Defining the context AI needs and injecting it to build documentation platforms.</li><li><strong>System-level Information Architect:</strong> Defining documents that AI reads well, setting standards for documents AI writes, and evaluating their quality.</li><li><strong>Documentation Expert:</strong> Applying specialized documentation platforms to provide feedback, and writing or providing the information AI needs.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WuYuw8D92NJSSCRE5Fpzxg.jpeg" /></figure><p>Now, let’s look at what each path actually involves and where they are headed.</p><h3>Document Engineer</h3><p>I wondered, “When did I start using this term?” and found it in <a href="https://lyingdragon.medium.com/%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%84%B0%EB%8A%94-%EB%AC%B4%EC%97%87%EC%9D%BC%EA%B9%8C-7f036b21dabd">the very first post</a> I wrote on Medium back in 2018. Happily, I also saw “docs engineer” on the LinkedIn profile of Fabrizio Ferri Benedetti, a technical writer and owner of the <a href="https://passo.uno/"><em>Passo Uno</em></a> blog.</p><p>Even before the AI era, document engineers worked on efficiency — developing documentation tools, automating repetitive tasks, and building pipelines that included verification. AI is essentially a tool that lets document engineers do these things “faster and correctly.”<strong> If you’ve already been doing this kind of work, the AI era isn’t a crisis; it’s an opportunity</strong>, and this is the perfect path for you.</p><p>Before AI, you’d sometimes hear, “Why is a technical writer coding? Leave it to the dev team!” But now, everyone codes. In a way, work that used to be “unauthorized” has finally moved into the “authorized” zone. Moreover, people who couldn’t try it before due to development hurdles can now jump in.</p><p><strong>The most important task for a document engineer in the AI era is creating</strong> <strong>“AI Agents for Documentation.”</strong> Big Tech is likely already using them, and I suspect several other companies are realizing their importance and preparing them. What this agent looks like depends on the company’s purpose and how they document things. From my perspective, we can break it down into three categories:</p><ol><li><strong>(For Technical Writers)</strong> Making the documentation tools we’ve built require less time to use.</li><li><strong>(For Developers)</strong> Automatically generating drafts that developers used to write themselves.</li><li><strong>(For Myself and Managers)</strong> Automating the document management/evaluation research we’ve been agonizing over.</li></ol><p>Let’s group these three things together and call it a “Documentation Platform.” This has become possible because, thanks to AI, we can build a PoC (Proof of Concept) with fewer people, and there are points we can solve without traditional coding. <strong>My team has already done a PoC for task #2, and we are currently expanding it while prototyping task #3</strong>.</p><p><strong>A documentation platform is the ultimate goal for a document engineer in the AI era</strong>. Before getting there, it’s worth trying tasks like the automation engineering Tom Johnson mentioned, or document verification using linters or LLMs. Gathering these one by one to create a pipeline and packaging them for reuse will eventually become the foundational elements of a platform.</p><h3>System-level Information Architect (= Content Director)</h3><p>This role is similar to the “content director” suggested by Tom Johnson and Fabrizio Ferri Benedetti in the video. Because the term “Information Architect” is already well-known, it’s easy to think of this as just expanding on existing work. However, I think it might actually be a new role emerging in the AI era. In that sense, “content director” might be a better fit.</p><p>A System-level Information Architect creates standards for technical documents in the AI era and verifies their quality. Pondering questions like <strong>“What makes a document easy for AI to read?”, “How do we get AI to write well?”, and “ Is the document written by AI actually correct?” </strong>are things we didn’t do before. While the third point could apply to human-written documents, the things AI can do differ from what humans can do, so the quality standards inevitably differ. You can’t view it as exactly the same job.</p><p>In short, a System-level Information Architect has to carve out this new role themselves. Fortunately, the AI era has advanced enough that there is a direction:</p><ol><li>Defining the types of documents AI will write and the information required for each type.</li><li>Creating technical writing guides suitable for AI to improve document <strong>discovery</strong>.</li><li>Setting document quality standards and establishing measurement methods based on them.</li><li>Building an <strong>ontology</strong> based on internal technical knowledge and document information.</li></ol><p><strong>My team has prototyped #1 and #3</strong>, but we need to handle them a bit more realistically. Personally, <strong>I’m experimenting with #2</strong>. Since #3 connects to building RAG (Retrieval-Augmented Generation), it’s easy to reuse existing tools for the measurement itself.</p><p>Of course, since every company has different priorities, the specifics of this role might vary a bit.</p><h3>Documentation Expert</h3><p>According to <a href="https://idratherbewriting.com/blog/tech-comm-predictions-for-2026#1-ai-hype-levels-off"><em>12 predictions for tech comm in 2026</em></a> by Tom Johnson, tech companies are looking for a few specialists rather than generalists. It seems unlikely that the demand for traditional writing skills in technical writing will increase.</p><p>Some people see the term “Documentation Expert” as just fancy packaging for technical writing, but I used this term to distinguish a specific value separate from general technical writing. Just doing technical writing for a long time doesn’t automatically make you an expert. <strong>To be an expert, you need domain expertise, the ability to survey the entire technology of that field</strong>, and the skill to capture scattered technical info and turn it into knowledge. The word “curator” came up in the video mentioned earlier, and I believe the “ultimate move” of a documentation expert is exactly that: Technical Curation. (I briefly touched on technical curation in my post <a href="https://lyingdragon.medium.com/author%EC%99%80-writer-5f2e326430b7#f540"><em>Author and Writer</em></a><em> (Korean only)</em>).</p><p>Now, let’s think about the role of a documentation expert in the AI era.</p><p>When I’ve had AI write meeting minutes, I’ve often seen it record information I thought was trivial during the meeting as a critical “blocking point.” This means <strong>AI doesn’t know which content is important and which can be glossed over</strong>. Since <strong>you need specialized knowledge to determine the importance</strong> of information, the only person who can verify the document written by AI is the documentation expert. To summarize the role:</p><ol><li>Providing professional context so AI generates correct output.</li><li>Using the AI agents made by the Document Engineer to verify if they fit actual projects well, and improving them.</li><li>(Referring to the video) Writing llms.txt (a guide for external LLMs to understand public doc content) and agent.md (writing rules in the source repo).</li></ol><p>Because they are the ones who can infuse AI with specialized knowledge and long experience, they can truly be called the select few experts.</p><h3>Let’s Define Our Own Path</h3><p>These three paths are suggestions based on my experience, so they might not fit every technical writer. There might be paths I haven’t thought of, or you might choose to walk a combination of these paths.</p><p>However, I believe that <strong>technical writers themselves should be the ones to define their new roles in the AI era.</strong> Instead of waiting for someone to create a role for you, if you think about what you should do in the AI era based on the work you’ve done so far, won’t the path naturally reveal itself?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7def1e1bf900" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Will AI Replace My Job?]]></title>
            <link>https://lyingdragon.medium.com/will-ai-replace-my-job-9d782f7f7b48?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/9d782f7f7b48</guid>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sat, 17 Jan 2026 12:03:08 GMT</pubDate>
            <atom:updated>2026-01-17T12:03:08.066Z</atom:updated>
            <content:encoded><![CDATA[<p>English version of <a href="https://lyingdragon.medium.com/ai%EA%B0%80-%EB%82%B4-%EC%A7%81%EC%97%85%EC%9D%84-%EB%8C%80%EC%B2%B4%ED%95%A0%EA%B9%8C-6ecfc3449505">this story</a>.</p><p>There’s been a lot of bad news lately about AI taking over jobs. Big tech companies are pouring more money into AI and cutting staff. Everyone seems to be saying the same thing: if you fall behind in AI, you’re done.</p><p>Some say writing jobs are especially vulnerable. When I switched from engineering to technical writing, friends used to tease me: “Why choose a job that gets cut first?” But this feels different. Developers and writers alike are now hearing that <em>even “safe” jobs</em> could be at risk.</p><p>So the real question is this: <strong>Can LLMs actually replace what I do?</strong></p><h4>What I’ve Seen Working With AI</h4><p>In some projects, AI tools can do astonishingly good work. For example, give a code snippet and ask an AI to write API documentation, and it will output something reasonable. This looks impressive at first.</p><p>But here’s the catch: technical writing isn’t just formatting text nicely. Good technical docs explain <em>context</em>, <em>why things matter</em>, and <em>what to watch out for</em>. AI doesn’t understand company-specific terminology or hidden logic unless you give that context first. That’s still a human job.</p><p><strong>What AIs generally write:</strong></p><pre>/* Retrieves the customer tier in My System that matches the given `mid`.<br> * @param {String} mid Middle ID<br> * @return The tier of the customer with the given `mid`<br> */<br>public int getCustomerGradeOfMySystem(String mid) {<br>   ...<br>}</pre><p><strong>What technical writers write:</strong></p><pre>/**<br> * Retrieves the customer tier in My System that matches the given `mid`.<br> * Before calling this API, you must first call ooo() to complete authentication.<br> * @param {String} mid Unique LINE Messenger account ID. See [`mid`](internal_glossary_link).<br> * @return The tier of the customer with the given `mid`.<br> *         If an error occurs, -1 is returned. If the customer has no assigned tier, 0 is returned. For detailed information about customer tiers, see the [policy document](https://xxx).<br> */<br>public int getCustomerGradeOfMySystem(String mid) {<br>   ...<br>}</pre><h4>Where AI Helps — But Doesn’t Replace</h4><p>AI can dramatically speed up parts of the work:</p><ul><li>First draft generation</li><li>Basic formatting</li><li>Use of custom glossary if given</li></ul><p>But it struggles with things like:</p><ul><li>Inferring unstated assumptions</li><li>Choosing the right examples for a specific audience</li><li>Aligning explanations with real workflows</li></ul><p>Those decisions come from experience, not pattern recognition.</p><p>In other words, AI is <em>a powerful assistant</em>, but not a replacement for deep professional judgment.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ASBnr80XCyLNHXXw7QgscQ.png" /><figcaption>What AI Is Good and Bad at in Code-Based Writing (Blue: Good, Orange: Poor)</figcaption></figure><h3>Dealing With Value Conflicts: Fundamentals and Adapting to Change</h3><p>The problem is not just quality. It’s a conflict of values. As a technical writer, the sense of crisis I feel does not come from AI, but from people.</p><p>People may think that LLMs write better than technical writers. They may find it more convenient to have an LLM write documents instead of dealing with a technical writer who takes time and keeps asking questions. A company may decide that even if quality drops a bit, it is more cost-effective to have AI produce documentation than to hire another person.</p><h4>How should I respond to this way of thinking?</h4><p>Shouting “AI-written documents are low quality!” a hundred times won’t help. The only way is to prove value through results. Right now, in a world where the free beta period is over, I need to prove why I matter.</p><p>I don’t yet have a clear answer on how exactly to do that, but I think the following two things are essential in that process.</p><ul><li><strong>Fundamentals</strong>: To answer the question, “If AI writes, what are you going to do?” with “I’ll teach LLMs,” you need solid fundamentals. Without them, you end up competing directly with LLMs on basic writing skills, and that’s not an easy competition to win.</li><li><strong>Adapting to change</strong>: To answer the question, “What value does your work have in the AI era?” with “I will create this new kind of value,” you need to accept change and respond to it. Techniques and experience learned ten years ago may no longer be useful. If so, as unfortunate as it may feel, you have to let go of old knowledge and experience and take in new ones.</li></ul><h3>Role Changes in the AI Era</h3><p>In the end, the answer to “Will AI replace my job?” is “It might.” But the fundamentals I have and the value I create will still be used. The role may no longer be called “technical writer,” but there’s no need to be attached to the title or to specific tasks. If the work I do creates value and that value is recognized, that becomes my job.</p><p>A few months ago, I watched a video where Google technical writer Tom Johnson and Elastic technical writer Fabrizio Ferri Benedetti discussed how the role of technical writers will change in the AI era.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FX9Dzu7nltUg%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DX9Dzu7nltUg&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FX9Dzu7nltUg%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/2f515b66b60974eed9d90870a34451f4/href">https://medium.com/media/2f515b66b60974eed9d90870a34451f4/href</a></iframe><p>They argued that technical writers will need to evolve into roles like context curators or content directors. More recently, Tom Johnson wrote on his blog that technical writers will also need to take on automation engineering.</p><p>The terminology isn’t exactly the same, but I’ve been thinking along similar lines.</p><ul><li><strong>Document engineer</strong>: A role I am already doing, but need to do more intensely. Defining the context AI needs and injecting it to build a documentation automation platform. (This includes automation engineering work.)</li><li><strong>System-level information architect</strong>: Defining documents that AI can read well, setting standards so AI operates correctly, and measuring quality. (Similar to a content director.)</li><li><strong>Documentation expert</strong>: Applying automation platforms to real documentation, identifying issues and providing feedback, and finding and writing documents AI needs. (Similar to a context curator.)</li></ul><p>I’ve shared this internally with my team, and I might write about it in more detail in the next post.</p><p>I am both a technical writer and an engineer. These days, about 90 percent of my work is engineering rather than writing. I’ve always been interested in automation and efficiency, so I started automating parts of documentation work one by one, adding ideas and organizing features that could be automated. When AI appeared, it felt like things I had only imagined were suddenly becoming real. Because of that, I feel more anticipation than fear about AI.</p><p>That said, there are things I regret. The documentation experience I’ve accumulated might become a “retired skill” that no one looks for anymore. I still like writing, but writing itself may become something humans no longer do.</p><p>Still, lately I’ve been reminded that I can’t do only what I like and still live exactly the way I want in a company. Even if it’s disappointing, it’s time to let some things go. <a href="https://youtu.be/Gm-l_Bgt7Ic?si=-eE3X5Lp-z6JT6zh">As Sam Altman has said</a>, when calculators first appeared, people were skeptical, but now everyone benefits from them. Even if it feels like a loss now, letting go and looking at something new might lead to another kind of enjoyment. As for writing, which I still love, I can keep doing it personally, just like this.</p><p><strong>Next story</strong>:</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9d782f7f7b48" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI시대 테크니컬 라이터의 길]]></title>
            <link>https://lyingdragon.medium.com/ai%EC%8B%9C%EB%8C%80-%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%84%B0%EC%9D%98-%EA%B8%B8-0f460fb192e0?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/0f460fb192e0</guid>
            <category><![CDATA[discussion]]></category>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sat, 17 Jan 2026 12:02:49 GMT</pubDate>
            <atom:updated>2026-01-19T03:42:17.265Z</atom:updated>
            <content:encoded><![CDATA[<p>AI가 글을 써주는 시대라면, 테크니컬 라이터는 무슨 일을 해야 할까? ‘기술 문서 잘 쓰기’만으로는 부족하다면? 지난 글에 이어서, 내가 생각한, AI 시대 테크니컬 라이터가 갈 길을 정리해보려고 한다.</p><p><a href="https://lyingdragon.medium.com/ai%EA%B0%80-%EB%82%B4-%EC%A7%81%EC%97%85%EC%9D%84-%EB%8C%80%EC%B2%B4%ED%95%A0%EA%B9%8C-6ecfc3449505">AI가 내 직업을 대체할까?</a></p><p>지난 글과 더불어 그때 언급한 영상 <a href="https://youtu.be/X9Dzu7nltUg?si=ZwUXY1AV8IaHNOTg">&lt;How AI is changing the role of technical writers to “context curators” and “content directors”&gt;</a>를 참고하면 좋겠다.</p><p>지난 글에서 세 가지 길을 제안했다.</p><ul><li><strong>Document engineer: </strong>AI에 필요한 컨텍스트를 정의하고 이를 주입해서 문서화 플랫폼을 구축하는 길.</li><li><strong>System-level information architect</strong>: AI가 잘 읽는 문서를 정의하고, AI가 쓸 문서 기준을 제시하고 그 품질을 평가하는 길.</li><li><strong>Documentation expert</strong>: 전문 분야의 문서화에 플랫폼을 적용해 피드백하고, AI에 필요한 정보를 작성하거나 제공하는 길.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pUz2xrH5hYJI3LPjrl9vyA@2x.jpeg" /></figure><p>이제 각 길이 어떤 일을 하는지, 어떤 방향으로 나아갈지 살펴보자.</p><h3>Document engineer</h3><p>‘내가 이 단어를 언제부터 썼더라’하며 찾아보니, 2018년에 <a href="https://lyingdragon.medium.com/%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%84%B0%EB%8A%94-%EB%AC%B4%EC%97%87%EC%9D%BC%EA%B9%8C-7f036b21dabd">Medium에 쓴 첫 글</a>에서 나온다. 반갑게도, <a href="https://passo.uno/">Passo Uno</a> 블로그 주인, 테크니컬 라이터 Fabrizio Ferri Benedetti의 LinkedIn 프로필에도 “docs engineer”가 들어있다.</p><p>이건 내가 가고 있는 길이어서 정의하기가 쉬웠다.</p><p>AI 시대가 되기 전에도 document engineer는 작업 효율화를 목표로, 문서화 도구 개발, 반복 업무 자동화, 검증을 포함한 파이프라인 구축 같은 작업을 수행했다. AI는 document engineer가 이런 일을 “더 빠르게, 올바로 하게 해 줄” 도구에 가깝다. <strong>이미 이런 일을 해왔다면 AI 시대는 위기보다는 기회</strong>이며, 이 길을 가기에도 알맞다.</p><p>AI 시대 이전에는 “테크니컬 라이터가 왜 개발해? 개발팀에 맡겨!”라는 말도 가끔 들었는데, 이제는 누구나 개발하는 시대다. 어떻게 보면 무허가로 하던 일이 허가권에 들어간 셈이다. 더욱이 그간 개발 허들 때문에 시도하지 못한 사람도 할 수 있게 됐다.</p><p><strong>AI 시대 document engineer가 해야할 가장 중요한 일은 ‘문서용 AI 에이전트’를 만드는 일</strong>이다. 빅테크는 이미 만들어 쓰고 있을 테고, 몇몇 회사도 중요성을 깨닫고 준비중일 것으로 생각한다. 이 에이전트가 어떤 모습이 될지는, 그 회사에서 어떤 목적으로 어떻게 문서화하고 있는지에 따라 다르다. 내 입장에서는, 세 가지로 나눠볼 수 있다.</p><ol><li>(테크니컬 라이터를 위해) 지금껏 만들어온 문서화 작업 도구를 시간을 덜 들이고 쓰게 하는 것</li><li>(개발자를 위해) 개발자들이 쓰던 초안을 대신 만들어주는 것</li><li>(나 자신과 관리자를 위해) 그간 고민하고 연구해온 문서 관리/평가를 자동화하는 것</li></ol><p>이 세 가지를 묶어서 ‘문서화 플랫폼’이라고 부르자. 이게 가능해진 이유는 AI 덕분에 적은 인력으로도 PoC를 만들 수 있고, 전통적 코딩이 아니더라도 해결할 수 있는 포인트가 있기 때문이다. <strong>우리 팀은 2번 업무 하나를 PoC했고, 지금은 이를 확장하면서, 3번 업무 프로토타입을 만들고 있다</strong>.</p><p><strong>문서화 플랫폼은 AI 시대 document engineer의 최종 지향점</strong>이다. 그전에는 Tom Johnson이 언급한 자동화 엔지니어링, 린터(linter)나 LLM을 활용한 문서 검증 같은 작업을 시도해봄이 좋겠다. 그걸 하나둘 모아 파이프라인을 만들고 재활용할 수 있도록 패키징하면 플랫폼의 기초 요소가 될 테니까.</p><h3>System-level information architect(= Content director)</h3><p>영상에서 Tom Johnson과 Fabrizio Ferri Benedetti가 제시한 content director와 유사한 역할이다. 이미 잘 알려진 ‘information architect’라는 단어 때문에 본래 하던 일을 확장하는 걸로 생각하기 쉬운데, 오히려 AI 시대에 새롭게 생겨나는 역할이 아닐까 싶다. 그런 면에서는 content director라는 표현이 좀 더 나을 수도 있다.</p><p>System-level informations는 AI 시대 기술 문서의 기준을 만들고 품질을 검증한다. <strong>AI가 잘 읽는 문서는 무엇인가, AI가 문서를 잘 쓰게 하려면 어떻게 해야 하는가, AI가 쓴 문서가 정말 올바로 쓰였는가하는 고민은 예전에는 하지 않았던 일</strong>이다. 세 번째 일은 사람이 쓴 문서에도 적용할 수 있겠지만, AI가 할 수 있는 일과 사람이 할 수 있는 일이 달라서 품질 기준도 달라질 수밖에 없기에, 완전히 같은 일이라고는 볼 수 없다.</p><p>즉, system-level information architect는 새로운 역할을 스스로 만들어야 한다. 다행히, AI 시대도 어느 정도 발전했으므로 방향성은 있다.</p><ol><li>AI가 작성할 문서 유형과 각 유형에 필요한 정보 정의</li><li>AI에 적합한 기술 문서 작성 가이드를 만들어 작성한 문서의 검색(discovery) 향상</li><li>문서 품질 기준을 세우고 이를 근거로 측정 방법 마련</li><li>사내 기술 지식과 문서 정보를 바탕으로 온톨로지 구축</li></ol><p>우리 팀은 <strong>1번과 3번을 프로토타입으로 진행</strong>해봤는데 좀 더 현실적으로 처리해봐야 할 것 같다. <strong>개인적으로는 2번 작업</strong>을 해보고 있다. 3번 작업은 RAG 구축과 연결되기도 해서, 측정 자체는 이미 있는 도구를 재활용하기 좋다.</p><p>물론 회사마다 중점을 두는 곳이 다른만큼 이 역할이 할 일도 조금 달라질 수 있다.</p><h3>Documentation expert</h3><p>Tom Johnson이 쓴 &lt;<a href="https://idratherbewriting.com/blog/tech-comm-predictions-for-2026#1-ai-hype-levels-off">12 predictions for tech comm in 2026</a>&gt;에 따르면, 테크 기업은 generalist 보다는 소수의 specialist를 찾고 있다. 테크니컬 라이팅 업무에서도 전통적인 글쓰기 역량(traditional writing skills) 수요가 늘어날 가망이 낮아 보인다.</p><p>Documentation expert라는 단어를, 테크니컬 라이팅의 보기 좋은 포장지로 보는 사람도 있지만, 나는 이 단어를 쓰면서 일반적인 테크니컬 라이팅과는 구별되는 가치를 생각했다. 테크니컬 라이팅을 오래한다고 해서 모두 전문가가 될 수는 없다. <strong>전문가가 되려면 도메인 전문 지식을 갖추고서 그 분야의 기술 전체를 조망하며 사방에 흩어진 기술 정보를 포착해 지식으로 만들 수 있어야</strong> 하니까. 앞서 언급한 영상에서도 ‘curator’라는 단어가 나왔는데, documentation expert의 궁극기는 바로 그 ‘기술 큐레이션’이라고 생각한다. (기술 큐레이션은 <a href="https://lyingdragon.medium.com/author%EC%99%80-writer-5f2e326430b7#f540">&lt;Author와 writer&gt;에서 잠시 말한 바</a> 있다.)</p><p>이제 AI 시대의 documentation expert 역할도 생각해보자.</p><p>AI로 회의록을 써 보면, 회의할 때는 별로 중요하지 않다고 생각한 정보가 최악의 블로킹 포인트로 기록된 걸 종종 봤다. <strong>AI는 주어진 콘텐츠 중 중요한 내용과 대충 흘려도 되는 내용이 무엇인지 모른다는 뜻</strong>이다. <strong>정보의 중요도를 알려주려면 전문 지식이 있어야</strong> 하므로, 결과적으로 AI가 쓴 문서를 검증할 수 있는 사람은 documentation expert다. 역할을 정리하면 이렇다.</p><ol><li>AI가 올바른 출력을 내도록 컨텍스트(중요도 선별 필요)를 제공</li><li>Document engineer가 만든 AI 에이전트를 사용해 실제 프로젝트에 잘 맞는지 검증하고 개선</li><li>(영상을 참고하자면) llms.txt(외부 공개 문서로서 외부 LLM이 문서 내용을 잘 파악할 수 있도록 가이드)과 agent.md(소스 저장소의 작성 규칙) 작성</li></ol><p>한 분야의 전문 지식과 오랜 경험을 갖추어야만 AI에 녹여낼 수 있다는 점에서 이들이야말로 소수의 전문가라고 할 수 있다.</p><h3>스스로 길을 정의하자</h3><p>이 세 가지는 내 경험을 바탕으로 제안한 길이어서 모든 테크니컬 라이터에게 맞지 않을 수도 있다. 내가 생각하지 못한 길이 있을 수도 있고, 세 가지 길 중 여러 개를 선택해서 갈 수도 있다.</p><p>하지만 <strong>AI 시대 새로운 역할을 정의하는 일은 테크니컬 라이터 자신이어야 한다</strong>고 생각한다. 누군가 역할을 만들어주길 기다린다면 그 길에서 주도권을 잡기 어렵고, 자칫하면 원치 않은 길로 끌려갈 수 있다. 반대로, 자신이 해온 일을 바탕으로 AI 시대에 무엇을 해야할지 고민해보면 자연스럽게 길이 보이지 않을까?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0f460fb192e0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI가 내 직업을 대체할까?]]></title>
            <link>https://lyingdragon.medium.com/ai%EA%B0%80-%EB%82%B4-%EC%A7%81%EC%97%85%EC%9D%84-%EB%8C%80%EC%B2%B4%ED%95%A0%EA%B9%8C-6ecfc3449505?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/6ecfc3449505</guid>
            <category><![CDATA[technical-writing]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sun, 11 Jan 2026 08:01:37 GMT</pubDate>
            <atom:updated>2026-01-18T09:18:19.253Z</atom:updated>
            <content:encoded><![CDATA[<p>작년 말부터 살벌한 이야기들이 들려온다. 빅테크 기업이 AI 투자를 늘리며 인력을 감축한다는 뉴스, “AI에 뒤처지면 끝장”이라고 말하는 듯한 유튜브 영상과 LinkedIn 포스트.</p><p>“글 쓰는 직무는 위험하다”는 말은 내게 별로 새롭지 않다. 개발자를 관두고 테크니컬 라이터로 전향했을 때도 “왜 유망한 직무를 버리고, 회사 어려워지면 제일 먼저 잘리는 직무로 가냐”는 소리를 들었으니까.</p><p>하지만 이번 위기는 좀 다르다. 글 쓰는 직무뿐만 아니라 개발 같은 유망한 직무 역시 위기라는 말이 오가니까.</p><p><a href="https://www.bloodinthemachine.com/s/ai-killed-my-job">AI Killed My Job</a>이라는 포스트에 따르면, 빅테크에서는 엔지니어, 비 엔지니어 할 것 없이 AI로 인한 해고, 변화로 인한 갈등이 실제로 일어나고 있다. Microsoft가 발표한 논문, <a href="https://arxiv.org/pdf/2507.07935">Working with AI: Measuring the Applicability of Generative AI to Occupations</a>에는 AI를 적용하기 좋은 직무 중에 테크니컬 라이터가 상위권에 올라 있다(발표 시점에는 18위였는데 그 사이 13위로 뛰었음).</p><p>하긴, LLM이라는 친구는 나보다 글을 빨리 쓰고, 내가 못하는 다국어 번역도 순식간에 해치운다. <strong>그러면 LLM은 정말 내 직업을 대체할 것인가?</strong></p><h3>AI로 글쓰기 하면서 느낀 것</h3><p>AI로 API 레퍼런스를 작성하는 프로젝트를 하다 보니, “와, 이게 되네?!” 싶은 것도 많고 “와, 이게 안 되네?” 싶은 것도 많았다.</p><p><a href="https://techblog.lycorp.co.jp/ko/give-me-the-code-and-then-ai-and-i-will-provide-the-api-reference-for-you">AI와 글쟁이의 동행: 코드 주면 API 레퍼런스 써드려요</a></p><h4>AI와의 동행: 와, 이게 되네?</h4><p>LLM은 코드도 잘 읽고, 글도 잘 쓰고, 수많은 API 레퍼런스를 학습했기에 기본적으로 잘 쓴다. 더도 덜도 말고 코드를 주면서 “JSDoc 스타일 API 주석 써줘”라고 하면 이렇게 만들어준다.</p><pre>/**<br> * 주어진 `mid`에 맞는 My System의 고객 등급을 가져옵니다.<br> * @param {String} mid 중간 ID<br> * @return 입력한 `mid`를 가진 고객의 등급<br> */<br>public int getCustomerGradeOfMySystem(String mid) {<br>   ...<br>}</pre><p>내 경험에 따르면, 개발자에게 써달라고 해도 이 정도로 써주니까 이 정도만 해도 “와!” 싶다. 개발자 입장에서는 평소 직접 쓰던 걸 AI가 해주니 문서화 시간을 100% 절감한 셈이다. 충분히 만족스러운 결과다.</p><p>그런데 조그만 문제가 있다. 이 코드에서 mid는 LINE 메신저에서 사용하는 고유 용어다. 웹에 공개된 정보이니 운이 좋으면 LLM이 알 수도 있지만, 그렇지 않은 사내 용어는 판단하지 못한다. 그럴 때 사내 용어집을 컨텍스트로 제공하면 제법 기특한 결과를 낸다.</p><pre>/**<br> * 주어진 `mid`에 맞는 My System의 고객 등급을 가져옵니다.<br> * @param {String} mid LINE 메신저 계정 고유 ID. [`mid`](사내_용어집_링크)를 참고하세요.<br> * @return 입력한 `mid`를 가진 고객의 등급<br> */<br>public int getCustomerGradeOfMySystem(String mid) {<br>   ...<br>}</pre><h4>AI의 한계: 와, 이게 안 되네?</h4><p>이 정도로도 충분해 보이지만, 테크니컬 라이터에겐 만족스럽지 못하다.</p><p>API 설명에서 파라미터와 반환값 범위를 명시하는 건 필수인데, AI는 그냥 하라고 하면 그걸 안 한다. 특히 이 함수처럼 숫자로 표현하지만 의미가 담긴 정보라면 더 그렇다.</p><p>예를 들어, 이 함수의 반환값인 ‘등급&#39; 숫자는 이런 의미라고 하자.</p><blockquote>0: 등급 없음. 1: 실버, 2: 골드: 3: 플래티넘</blockquote><p>AI가 주석을 쓸 때 이 정보를 알려면 둘 중 하나가 전제되어야 한다.</p><ol><li>반환값을 enum으로 설정하고, enum에 CUSTORMER_GRADE_SILVER처럼 등급 이름 명시</li><li>코드 내 주석으로 설명하거나 등급 정보가 담긴 기획 문서를 컨텍스트로 제공</li></ol><p>이게 없다면 AI는 죽었다 깨어나도 이 정보를 써내지 못한다. 사람이 맥락을 주고 설명하라고 해야 작동한다.</p><p>하나 더 있다.</p><p>테크니컬 라이터는 API 사용자 입장에서 생각한다. “이 API를 사용하기 전에 사용자가 먼저 해야 할 일은 없는가?” 같은 생각이다. 예를 들어, 이 API를 호출하기 전에 연결할 시스템을 지정하고 그 시스템에 인증을 하도록 기획(=의도)했다면, 그 정보를 써야 한다.</p><p>하지만, AI는 코드에 나와있지 않은 의도를 파악하지 못한다. 이런 정보는 어디에 있는가? 문서화가 잘 된 프로젝트라면 기획서나 설계서에 기록되어 있을 것이다. 혹은 슬랙 메시지라도…. 최악의 경우는 기획한 사람과 설계한 사람 머리에만 남아 있다.</p><p>경험 많은 테크니컬 라이터는, 명시적으로 드러나지 않은 중요한 정보를 예상하고, 그 정보를 아는 누군가를 찾아 답을 끄집어낸다. AI는 그걸 못하니, 이 또한 사람이 그렇게 알려주거나 스스로 찾아내도록 만들어야 한다.</p><h3>AI가 잘하는 것과 못하는 것</h3><p>‘코드를 보고 글쓰기’에서 AI가 잘하는 것과 못하는 것을 정리하자면 이렇다. 파란색은 잘하는 것이고 주황색은 못하는 것이다. 말하자면 개발자들이 흔히 써내는 초안(코드 기본 설명, 포맷 적용, 올바른 용어, 혹시 여기서 나아가 범위 명시)은 잘 쓰지만, 테크니컬 라이터가 쓰는 수준(상세 범위, 의도 파악)은 쓰지 못한다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/632/1*jICIxZD33S7FpuaMGTyn3w.png" /><figcaption>코드 보고 글쓰기에서 AI가 잘하는 것과 못하는 것 (파랑: 잘한다, 주황: 못한다)</figcaption></figure><h3>AI는 내가 가르칠 대상</h3><p>그렇다, LLM은 글을 잘 쓴다. 아마 테크니컬 라이터가 생각하고 끄집어낸 정보를 주고 이러저러하게 쓰라고 한다면, 누구보다 빠르게 여러 언어로 API 레퍼런스를 써낼 것이다. 하지만 그 정보가 없다면?</p><p>그렇기에 내게 있어 LLM이란, 코드도 잘 보고 글도 잘 쓰고 여러 언어도 하지만, 기술 글쓰기를 잘 모르는 학생이다. 어떻게 쓰는 게 잘 쓴 것인지, 어떤 정보를 넣어야 하는지 가르쳐주는 건 온전히 내 역할이다.</p><p>작년 말에 동료와 함께 쓴 기술 글쓰기 안내서 &lt;개발자는 글을 못 쓴다고요?&gt;가 출간되었다. 처음엔 시기가 좀 애매하다고 생각했는데, 다시 생각해 보면 LLM이야 말로 이 책의 가장 중요한 독자다. LLM을 이용해 기술 문서 쓰기를 해보려는 사람들이, 단순히 ‘자 AI, 코드 줄 테니 써봐!’라고 하지 않고 올바른 방법을 가이드하려면, 이 책을 참고해야 할 거라고 생각한다.</p><p><a href="https://www.yes24.com/product/goods/163591750">개발자는 글을 못 쓴다고요? | 전정은 | 제이펍 - 예스24</a></p><p>물론 앞서 말한 것처럼 무엇을 써야 할지 안다 하더라도, AI가 알아서 하지 못하는 일도 있다. 그 부분은 반드시 사람이 하거나, 사내 문서화 프로세스(모든 회의와 논의를 문서화하기 등) 수립과 AI 컨텍스트 엔지니어링으로 해결해야 할 것이다.</p><h3>가치관 싸움에 대처하는 방법: 기본기와 변화 대응</h3><p>문제는, 품질도 품질이지만, 가치관의 대립이다. 테크니컬 라이터로서 내 위기는, AI에서부터 오는 게 아니라 사람에서부터 오고 있다.</p><p>사람들은 LLM이 테크니컬 라이터보다 글을 잘 쓴다고 생각할 수 있다. 시키면 한참 걸리고, 귀찮게 자꾸 묻는 테크니컬 라이터보다 LLM에 맡겨서 글 쓰는 게 더 편하다고 생각할 수 있다. 회사는 퀄리티가 조금 떨어져도 사람 1명을 더 채용하느니 AI로 문서 써내게 하는 게 이익이라고 생각할 수 있다.</p><p><strong>나는 이런 그들의 생각에 어떻게 대응할 것인가?</strong></p><p>“AI가 쓴 문서는 품질이 떨어져요!”라고 백날 외쳐봐야 무슨 소용일까. ‘결과로 증명하는 것’말고는 방법이 없다. 지금 나는, 무료 베타 버전이 끝난 세상에서 존재 가치를 증명해야 할 때다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/352/1*iKt5KVyrMIWtseeiP0xW5A.png" /></figure><p>증명 방법이 무엇인지는 아직 명확히 답을 찾지 못했지만, 그 과정에서 아래 두 가지가 중요하지 않을까 한다.</p><ul><li><strong>기본기</strong>: “AI 글 써주는 데 너는 뭐 할 거니?”라는 질문에 “난 LLM을 가르칠 거예요”라고 대답하려면, 든든한 기본기가 있어야 한다. 이게 없으면 LLM과 기본 글쓰기 능력을 놓고 경쟁해야 하는데 그건 쉽게 뛰어넘을 수 없다.</li><li><strong>변화 대응</strong>: “AI 시대에 네가 하는 일은 어떤 가치가 있어?”라는 질문에 “이런 새로운 가치를 만들겠습니다”라고 대답하려면, 변화를 받아들이고, 대응할 수 있어야 한다. 이젠 10년 전에 익힌 기법이나 경험이 도움이 되지 않을 수도 있다. 그렇다면 아쉽더라도 내가 알던 지식과 경험을 고집하지 말고 새 지식과 경험을 받아들여야 한다.</li></ul><h3>AI 시대 역할 변화</h3><p>결과적으로 “AI가 내 직업을 대체할까?”라는 질문의 답은 “그럴 수도 있다”이다. 하지만 내가 가진 기본기와 내가 만든 가치는 쓰일 것이다. 비록 그 이름은 ‘테크니컬 라이터’가 아닐 테지만, 이름에 연연하거나 세부적인 업무에 연연할 필요는 없다. 내가 하는 일이 가치를 만들어내고 그걸 인정받는다면 그게 곧 내 직업이니까.</p><p>몇 달 전에 이런 영상을 봤다. Google 테크니컬 라이터 Tom Johnson과 Elastic의 테크니컬 라이터 Fabricio Ferry Benedet가 AI 시대 테크니컬 라이터의 역할 변화를 토론한 내용이다.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FX9Dzu7nltUg%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DX9Dzu7nltUg&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FX9Dzu7nltUg%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/861f4546a5f53c257bf9f79139e4468b/href">https://medium.com/media/861f4546a5f53c257bf9f79139e4468b/href</a></iframe><p>이들은 앞으로 테크니컬 라이터는 Context curator나 Content director로 변모해야 한다고 했다. 최근 Tom Johnson은 자신의 <a href="https://idratherbewriting.com/blog/tech-comm-predictions-for-2026#1-ai-hype-levels-off">블로그</a>에서 테크니컬 라이터도 automation engineering을 수행해야 할 거라고 했다.</p><p>용어가 똑같지는 않지만, 나도 유사한 역할 변화를 생각했다.</p><ul><li><strong>Document engineer</strong>: 이미 하고 있지만 더 격렬하게 해야 할 역할. AI에 필요한 컨텍스트를 정의하고 이를 주입해서 문서화 자동화 플랫폼을 구축한다. (Automation engineering 업무를 포함하는 역할)</li><li><strong>System-level information architect</strong>: AI가 잘 읽는 문서를 정의하고, AI가 올바로 작동하도록 기준을 제시하고 그 품질을 측정한다. (Content director와 유사)</li><li><strong>Documentation expert</strong>: 실제 문서에 자동화 플랫폼을 적용하고 문제점을 발견해 피드백하며, AI에 필요한 문서를 찾아내 작성한다. (Context curator와 유사)</li></ul><p>팀에서 공유한 적이 있는데, 다음 포스팅에 이 내용을 써볼까 한다.</p><p>나는 테크니컬 라이터이기도 하지만 엔지니어이기도 하다. 사실 요즘 하는 일은 라이팅보다는 엔지니어링이 거의 90%다. 본래부터 자동화나 효율화에 관심이 많아서 문서화 업무 중 자동화할 수 있는 일을 하나둘 해보고, 여러 가지 상상을 보태 자동화할 기능을 정리해 왔다. 그러던 와중에 AI가 등장하면서 상상만 하던 기능이 현실화되는 것 같아서, AI로 인한 위기감보다는 기대감이 크다.</p><p>물론 아쉬움도 있다. 내가 그간 쌓아온 문서화 경험이 ‘아무도 찾지 않는 사장된 기술’이 될지도 모른다는 것. 여전히 글쓰기를 좋아하는데 이제 ‘글쓰기’는 사람이 하지 않는 일이 될지도 모른다는 것.</p><p>하지만 내가 좋아하는 것만 하면서, 내가 원하는 대로 회사 생활을 할 수 없다는 걸 요즘 들어 새삼스럽게 깨달았다. 아쉬워도 놓을 건 놓아보자. <a href="https://youtu.be/Gm-l_Bgt7Ic?si=-eE3X5Lp-z6JT6zh">샘 알트먼의 말</a>처럼 처음 계산기가 나왔을 때도 회의적인 반응이었지만 이젠 모두가 그 혜택을 누리지 않는가? 비록 지금은 아쉬워도 내려놓고 새것을 들여다보면 다시 재미있는 걸 찾아낼지도 모른다. 나 역시, 좋아하는 글쓰기는 지금처럼 이렇게 개인적으로 하면 될 테지.</p><p><a href="https://lyingdragon.medium.com/ai%EC%8B%9C%EB%8C%80-%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%84%B0%EC%9D%98-%EA%B8%B8-0f460fb192e0">AI시대 테크니컬 라이터의 길</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6ecfc3449505" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[변방 조직의 최종 목적지는 어디일까?]]></title>
            <link>https://lyingdragon.medium.com/%EB%B3%80%EB%B0%A9-%EC%A1%B0%EC%A7%81%EC%9D%98-%EC%B5%9C%EC%A2%85-%EB%AA%A9%EC%A0%81%EC%A7%80%EB%8A%94-%EC%96%B4%EB%94%94%EC%9D%BC%EA%B9%8C-197a9adde6d2?source=rss-fdfb4f7981f0------2</link>
            <guid isPermaLink="false">https://medium.com/p/197a9adde6d2</guid>
            <dc:creator><![CDATA[Ragina Jeon]]></dc:creator>
            <pubDate>Sun, 01 Jun 2025 04:11:01 GMT</pubDate>
            <atom:updated>2025-06-01T07:56:03.381Z</atom:updated>
            <content:encoded><![CDATA[<p>이따금 하는 나의 괜한 고민 이야기.</p><p>이 블로그 주제인 테크니컬 라이팅과 다소 동떨어진 이야기일 수 있지만, 회사의 전략적 목표와는 다소 떨어진, 테크니컬 라이터라는 변방의 직무에 있기에 생겨난 고민이니 써 본다.</p><p>팀을 맡으면서 내게 제일 먼저 주어진 책임은 <strong>“팀원들이 성장하게 하라”</strong>였다. 처음에는 당연하게 여겼다. 나 역시 좋은 팀을 만들고 싶고, 팀원들이 보람차게 일하기를 바라니까. 그렇게 1년이 지난 지금은 약간 혼란에 빠졌다.</p><h3>혼란 1. 모두가 성장해도 모두가 인정받지 못한다면?</h3><p>모두가 열심히 해서 성장하더라도, ‘상대 평가’라는 시스템 속에서는 모두가 인정받을 수 없다.</p><p>평가란, 비단 나만이 아니라 그 시스템에 들어있는 수많은 사람이 관심을 보이고 생각해 온 문제다. 그런데도 여태 이런 상황인 걸 보면 내가 혼란해한들 어쩔 수가 없다.</p><p>하지만 우리 같은 소규모 조직에서는 ‘<strong>팀 내 경쟁</strong>’이 특히 뼈 아파서, 해결책이 없다는 것을 알면서도 고민이 된다. 팀원 모두가 성장하도록 격려한 결과 실제로 모두가 성장해서 좋은 결과를 냈을 때, 그들 모두 좋은 평가를 받을 수 있을까? 좋은 성과를 내도 좋은 평가가 따라오지 않는다면, 열심히 성장해서 좋은 성과를 내라고 격려할 근거(또는 당근)는 무엇일까?</p><p>역량을 계발한 기쁨? 전에는 못했던 걸 해냈다는 보람?</p><p>다 좋다. 하지만 그 기쁨과 보람이 남에게 인정받지 못하는 상황이 수차례 이어져도 유지될까? 어쩌면 ‘자 여러분, 성장하세요! 그럼 인정받습니다!’ 하는 내 격려의 말은 거짓이 될 수도 있다.</p><blockquote>윌리엄 제임스는 말했다. “인간 본성의 가장 깊은 곳에 있는 원리는 <strong>인정받고 싶은 갈망</strong>이다.” 명심하라. 그는 ‘바람’이나 ‘욕망’, ‘열망’이라고 말하지 않았다. 그는 인정받고 싶은 ‘갈망’이라고 말했다. — &lt;데일 카네기 인간관계론&gt;</blockquote><p>최근에 모 회사의 임원분을 만나 이야기할 기회가 있었는데, 그곳에는 개인 평가가 없으므로 평가를 잘 받기 위해 한 팀에서 서로 경쟁할 필요가 없단다. 대신 조직 목표 달성 정도에 따라 모든 조직원이 같은 평가를 받는다던가. 규모 작은 조직에서 팀원 간의 경쟁을 지켜봐야 하는 내 입장에서는 아주 매혹적인 시스템이었다. 하지만, 모두가 같은 평가를 받는 방식에도 불만을 갖는 사람은 있기 마련이라 완벽한 해결책이 아닐 수도 있다.</p><p>어쩔 수 없이 경쟁해야 한다면, 이런 질문을 하지 않을 수 없다. 성과의 고하를 판단할 기준은 무엇인가? 매출과 직접 연관이 있는 조직이라면 기준이 명확할 수도 있지만 테크니컬 라이팅은 매출에 얼마나 기여했는지를 측정하기가 애매하다. 그렇다면 결국 정성적(이라 쓰고 깜깜이라고 읽음) 평가를 해야 한다.</p><p>본래 하던 일은 당연히 해야 할 일이니까 성과라고 할 수 없다는 이야기를 들었다. 그렇다면 새로운 일을 해야 한다는 말인데, 매번 새로운 일을 하기에, 테크니컬 라이팅 직무에는 한계가 있다. 우리 회사에서는, 테크니컬 라이터가 한 제품에 투입되면 제품 수명이 다하기까지(또는 정말 지쳐서 더는 못 하겠다고 손을 들기 전까지) 그 일을 계속한다. 따라서 새로운 일을 하려는 사람은 그렇게 하던 일에 더해 새로운 일까지 해야 하고, 그게 몇 년 이어지면 혼자서 몇 가지나 되는 프로젝트를 하는 상황에 부닥친다.</p><p>이런 방식은 개인이나 회사에 다 좋지 않다. 여러 가지 일을 동시에 하다 보면 한 가지 일에 집중하기 어려워 품질이 떨어지기 십상이다. 또, 새로운 일을 해서 좋은 평가를 받고 싶은 마음에 너나 할 것 없이 본래 하던 일을 팽개치면, 그 직무의 기반이 되는 일(=본래 하던 일)은 뒷전으로 밀려, 속된 말로 ‘광팔이’ 세상이 될 수도 있다.</p><p>아무튼 ‘새로운 일’이라는 기준이 별로라면, 하던 일을 계속하면서도 성과라고 판별할 수 있는 방법은 없을까? 아이디어가 하나 있다. <strong>새로운 접근 방식을 접목해 하던 일을 효율화하고, 그것을 다른 사람 일에도 적용해 기여하는 것</strong>이다. 8시간 하던 일을 6시간으로 줄이고, 남은 2시간 동안 그 방법을 다른 사람에게 전파하면, 다른 사람들은 2시간씩 아낄 수 있다. 절약 시간과 기여 대상 수를 수치로 나타내 성과를 측정하면 정량적인 평가가 되지 않을까? 그래서 요즘엔 팀원들이 한 일 중에 ‘공통으로 쓸 만한 효율화 방안’이 있는지를 살펴본다.</p><h3>혼란 2. 모두가 잘하면 소는 누가 키워?</h3><p>두 번째 의문점은 첫 번째 의문점과 이어진다. 팀원 모두가 성장해서 레벨 높은 일을 하려고 하면 레벨 낮은 일은 누가 할까? 어차피 성장해도 레벨 낮은 일을 할 수밖에 없다면, 성장하지 않고 레벨 낮은 일만 해도 되지 않나?</p><p>그런데 얼마 전에 임원들을 보필하며 조직의 높은 곳을 경험한 지인을 만나 이야기하다가, 우연히 이 의문의 답을 얻었다. 답은 바로 ‘<strong>조직의 성장</strong>’이다.</p><p>&lt;팀장의 탄생&gt;을 쓴 줄리 주오네 상황을 보자.</p><blockquote>성장하는 조직의 관리자에게는 사람을 잘 뽑는 일이 제일 중요하다고 해도 과언이 아니다. 나는 지금껏 수백 명을 면접하고 영입하는 데 힘을 보탰는데, 그 정도면 내가 입사할 당시의 전체 직원 수보다도 많은 수준이다!</blockquote><p>여기서 성장이란 역량의 발전보다는 조직 규모를 말한다. 헷갈리지 않게 ‘규모 성장&#39;이라고 표현하자. 이렇게 규모가 성장하는 조직이라면, 팀원들이 성장해 전보다 레벨 높은 일을 하면 새로운 사람을 뽑아 그 사람이 하던 일을 맡길 수 있다. 그렇게 팀원이 늘어나면 새로운 일을 찾거나 할 수 있는 기회도 더 생긴다. 팀원의 성장은 곧 조직의 성장을 부르고, 조직의 성장이 회사의 성장으로 이어지게 될 것이다.</p><p>이런 조직에 있다면 뭐가 걱정일까? 조직 성장에 도움될 만한 일을 마구 하면서 필요할 때마다 사람을 채용하면 되는데.</p><p>하지만 과연,<strong> 테크니컬 라이팅 조직은 과연 성장할 수 있는 조직인가? 테크니컬 라이팅 조직의 성장이 곧 회사의 성장인가?</strong></p><p>이 질문은 테크니컬 라이터가 아니라, 회사의 높은 분들께 해야 한다. 그분들은 테크니컬 라이터가 늘어나는 것을 원하는가, 아닌가?</p><p>우리 팀이 새로운 일을 계속 찾아 하면서도 본래 하던 일을 놓지 못하는 것은 조직 규모가 더는 커지지 않기 때문이다. 하는 일이 많아지고 팀원 역량도 늘어났지만, 사람 수는 늘지 못했다. 발전하고 싶은 마음에 하던 일과 새로운 일을 전부 껴안고 끙끙대면서 나아가고 있는데, 모두가 좋은 평가를 받을 수 있다거나 앞으로 누군가가 짐을 덜어줄 것이라는 확신도 없다.</p><p>테크니컬 라이터가 많기로는 우리나라에서 손에 꼽을 회사에 다니면서 이렇게 말하니 다소 기만이라고 생각할 수도 있겠다. 하지만 현시점의 머릿수가 아니라 변화 추세를 바탕으로 말하면, 지금 우리가 점점 규모가 커지는 조직이라고 말하긴 어려운 상황이다.</p><p>팀원을 성장하게 만들어야 하는 책임을 ‘양심의 가책을 느끼지 않고&#39; 이루어내려면 조직 규모가 성장해야 한다는 결론에 이르렀다. 조직이 성장하면 경쟁이 다소 완화되고(아무래도 3명일 때보다 30명일 때 상위 N%의 절대치가 커지니까), 역량을 높인 사람이 하던 일을 다음 사람에게 맡기고 좀 더 어려운 일에 도전할 기회도 생긴다.</p><p>그럼, 조직이 성장하려면 어떻게 해야 할까? 회사가 성장하는 건 필수지만, 그건 내 힘으로 어쩔 수도 없으니 논외로 하고, 성장하는 회사라는 가정하에 생각하자면, 결정권을 가진 높은 분이 우리 팀이 성장하기를 허락해줘야 한다. 그러려면 지금 우리가 하는 일이 꼭 필요하고 중요하다는 것을 알려야 한다. 광팔이가 아니라, 실제로 중요한 일을 하고 있어야 하는 건 너무나 당연하다.</p><p>특정 제품의 기술 문서를 작성하는 일도 꼭 필요하고 무척 중요한 일이다. 다만 그건 조직 규모 성장에 도움이 안 된다. 아, 물론, 그 제품이 어마어마한 매출을 냈고 기술 문서가 그 매출에 도움을 줬다면 큰 도움이 될 수 있다. 다른 제품을 낼 때 그 제품의 성공 경험을 바탕으로 새 테크니컬 라이터를 채용하려 할 테니까. 하지만 그게 아니라면? 이미 누군가가 그 제품 문서를 잘 쓰고 있는 상황에서 또 한 명을 채용할 이유가 없을 것이다.</p><p>그렇다면 소수 테크니컬 라이터가 할 수 있는 일 중에 조직의 성장을 끌어낼 중요한 일은 무엇일까? 나는 그게 ‘o명이 일해서 ooo에게 기여하는 일’, 다시 말해 단순히 기술 문서를 써주는 것이 아니라 쓰게 하는 일이라고 생각한다. <strong>전사 문서 프로세스와 그 문화를 다루는 일</strong> 말이다.</p><p>물론, 내 생각이 꼭 맞다는 보장도 없고, 맞다 하더라도 높은 분들과 회사가 그렇게 생각할지 알 수도 없다. 결국 설득할 수 있는지 아닌지는 내 역량에 달렸다는 말이다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=197a9adde6d2" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>