전체 글 (2586) 썸네일형 리스트형 AI The Docs 2024 - APIs.json으로 AI 에이전트가 좀 더 쉽게 정보를 이해하게 만들기 AI 에이전트가 API 문서를 이해하기 위해 단순히 OpenAPI, AsyncAPI 같은 API 명세만으로는 충분하지 않으며, API를 제대로 이해하고 활용하려면 전체 API 운영 정보를 기계가 읽을 수 있는 형태로 제공해야 한다고 강조합니다. 이런 정보를 제공할 수 있는 적절한 방법이 APIs.json이라고 합니다. APIs.json은 문서, 인증, 버전, 가이드 뿐 아니라 가격 정보까지 API 전반에 걸친 정보를 구조화해서 담을 수 있으며 확장할 수 있기 때문에 AI 에이전트가 적절하게 정보를 탐색할 수 있는 안내를 제공할 수 있다고 합니다. 웹사이트에서 sitemap.xml 파일을 SEO를 위해 활용한 것과 비슷한 개념이라고 할 수 있습니다. https://apisjson.org/https://.. 2025년 7월 테크니컬 라이팅 이런 저런 소식 7월 7일Docusaurus를 이용한 API 문서 플랫폼의 진화https://d2.naver.com/helloworld/6196427네이버 사내 기술 교류 행사인 NAVER ENGINEERING DAY 2025(5월)에서 발표되었던 세션이라고 합니다. 그래서 문서의 작성보다는 기술적으로 기존 문서화 플랫폼(Redoc)에서 새로운 플랫폼(Docusaurus)으로 전환하는 과정, 검색 기능(typesense)을 추가하는 과정, 버전에 따른 안정적이 배포 방식(Nubes) 등을 설명합니다.기존에는 Redoc 커뮤니티 버전을 사용하고 있었는데, 버그도 많고 앞으로 추가하려는 기능 제약, 성능 이슈 등의 문제로 좀 더 컨트롤이 가능한 오픈소스 문서화 플랫폼을 찾았고, Docusaurus를 선택했다고 합니다. * .. WTD 포틀랜드 2025 - 라이트닝 토크 모음 (2) Jennifer Evans: But did you die? Doing things scared두렵고 무서운 일이라도 시도했을 때 죽지 않는다. 그러니 괜찮다. 그런 격려의 메시지입니다. Michelle Knight: Document: your most valuable data asset메시지가 좀 모호하긴 한데, 조직 내에서 기술 문서도 데이터 자산으로 관리되어야 하고 이에 대한 거버넌스 체계가 필요하다는 이야기입니다.전통적인 데이터 거버넌스 범위는 실제 데이터에 초점을 맞추고 있지만, 최근에는 문서 역시 대상이 될 수 있다고 합니다. 좀 더 상세한 내용은 어떤 식으로 관리한다는 것인가를 찾아봐야 할 텐데, 그런 자료는 찾기가 쉽지 않네요. Ashley Gordon: I Come Back Stronger.. WTD 포틀랜드 2025 - 라이트닝 토크 모음 (1) Zaz Linkous: Game design in documentation 게임을 만들 때 마리오 1.1 이라는 것이 있다고 합니다(검색해 보면 World 1-1이라고 나옵니다). 게임을 시작할 때 안전한 환경에서 게임 조작법을 익히는 레벨입니다. 게임 디자인의 교과서 같은 것이라고 하네요. https://en.wikipedia.org/wiki/World_1-1하지만, 기술 문서에서는 World1-1같은 안전한 공간이 없습니다. 처음부터 혼돈의 세계에 던져지는 상황이 많죠. 때문에 게임 디자인의 원칙을 공부하면 좀 더 사용자가 안전한 환경에서 제품에 접근하도록 가이드할 수 있습니다(실제 클라우드 서비스 같은 경우에는 동작을 배우기 위해 비용이 들어가는데, 튜토리얼 같은 문서에서는 별도의 비용 없이 따라 .. 도움이 될 만한 12가지 릴리스 노트 예시 (소프트웨어 개발 및 협업 도구) 원문은 55가지를 소개하고 있는데 그 중에서 "소프트웨어 개발 및 협업 도구"에 해당하는 12가지만 소개해봅니다. 화면 캡처 시점이 2022년 11월인 것을 보면 이 글이 작성된 시점은 2023년 즈음이 아닌가 싶은데 Wayback Machine으로 확인해보면 2024년 하반기입니다(정확한 게시 일자를 확인할 수 없네요). Amoeboids는 아틀라시안 마켓플레이스 앱을 개발하는 IT 서비스 화시라고 합니다. 제품군 중에 자동으로 릴리스 노트를 생성하는 것이 있어 이런 콘텐츠를 만든 것이 아닌가 싶네요. https://amoeboids.com/atlassian-apps/automated-release-notes-for-jira/원문은 아래 링크를 참고하세요. https://amoeboids.com/bl.. WTD 포틀랜드 2025 - 커뮤니티와 같이 문서 만들기 Discord의 시니어 개발자 에반젤리스트 Colin Loretz가 문서를 누구나 기여할 수 있도록 '오픈'하고, 커뮤니티와 PR 중심으로 협업하며 얻은 교훈과 실질적 운영 노하우를 공유합니다. Discord는 오픈소스 제품은 아니지만, 문서는 공개된 GitHub 저장소에서 관리하며, 매달 30~50건의 PR 중 절반 이상이 커뮤니티에서 올라올 만큼 활발한 협업이 이루어지고 있습니다.https://github.com/discord/discord-api-docs 1. 오픈 문서의 의미와 효과 - 문서를 오픈하면 개발팀과 사용자와의 '공동 창작' 및 '공동 소유' 관계가 형성됩니다. - Discord는 공식 SDK 외에도 60개 이상의 커뮤니티 라이브러리(20개 이상 언어)를 지원하며, 이 생태계가 문서에 .. WTD 포틀랜드 2025 - 경쟁 분석을 통해 기술 문서 개선하기 이 발표에서 Leah Catania(Insulet의 시니어 콘텐츠 전략가)는 테크니컬 라이터와 콘텐츠 전략가가 "경쟁사 분석(Competitive Analysis)"을 활용해 문서 전략을 개선하고, 이해관계자(stakeholder)의 신뢰와 동의를 얻는 실질적인 방법을 공유합니다. 실제 경험과 구체적인 사례를 바탕으로, 경쟁사 분석의 준비, 실행, 결과 활용, 설득 전략까지 단계별로 설명합니다.(간혹, 실제 업무는 테크니컬 라이터인데 콘텐츠 전략가라고 소개하는 경우도 있는데, Insulet의 경우에는 테크니컬 라이터, UX 테크니컬 라이터, 콘텐츠 전략가 이런 식으로 상당히 세분화되어 팀을 구성하고 있습니다. 의료기기를 다루는 업체 특성인 것 같기도 합니다).1. 경쟁사 분석이란 무엇인가? 경쟁사 분석은.. WTD 포틀랜드 2025 - 조직 규모에 따라 테크니컬 라이터가 하는 일이 달라지나요 발표자는 현재 회사(Klaviyo)에 2019년 합류했는데 그 시점에 전체 구성원은 350명 정도였고 테크니컬 라이터는 3명이었다고 합니다. 이때는 스타트업 규모였고 테크니컬 라이터의 역할은 기술 문서뿐 아니라 온보딩, 마케팅, 블로그 관리 등 여러 가지 필요한 일들을 다 했어야 했습니다. 이 시기에 만든 콘텐츠 중에 사용자들이 주로 겪는 사례들을 FAQ 형태로 만든 콘텐츠가 300여개300여 개 정도 있었습니다. 하지만 여러 가지 일을 해야 하는 3명의 테크니컬 라이터에게는 관리하기 어려운 짐이 되어버렸습니다. 그런데 마침 외부 개발자 커뮤니티를 만드는 팀이 있었는데 그 팀에는 부족한 콘텐츠가 문제였습니다. 우리가 가지고 있는 300여 개의 부담스러운 콘텐츠는 그들에게 커뮤니티 게시물을 늘릴 수 있는 .. 이전 1 2 3 4 ··· 324 다음
