테크니컬 라이팅 (309) 썸네일형 리스트형 WTD 애틀랜틱 2023 - IA 개편 프로젝트 실패 공유 기존 문서는 이해하기 어렵고 원하는 정보를 찾기가 어려웠다고 합니다. 그래서 전반적인 정보의 재구성이 필요한 상황이었습니다. consul이라는 솔루션에 대한 문서가 2가지 형태로 나누어져 있었습니다. 하나는 Learn이고 하나는 docs입니다. 도메인 자체가 따로 나누어져 있기 때문에 서로 정보를 연결하기도 쉽지 않았습니다. 물론 이런 문제는 서비스를 하나로 통합하면 되는 것이라서 큰 문제는 아니었습니다. 정보를 재구성하는데 있어서 콘텐츠 자체를 다시 작성하는 것은 대응할 수 있는 규모가 아니었기 때문에 이를 배제하고 정보를 재구성하는 것에만 집중하기로 했습니다. 콘텐츠를 분류하고 정해진 주제에 따라 정보를 재배치했습니다. 탐색바부터 시작해서 사용자가 원하는 정보를 최소한의 클릭으로 찾을 수 있게 제공하.. WTD 애틀랜틱 2023 - 문서 작성자를 위한 OpenAPI 나름 시각화를 통해 설명을 시도한 것은 좋았으나 뒤로 가면서 OpenAPI에 대해 점점 더 알기 어렵게 설명하는 것이 아닌가 싶습니다. OpenAPI 문서화는 문서 작성자가 따로 없더라도 어느 정도 형식을 갖추어 만들 수 있기 때문에 문서 작성자에게는 기회가 될 수도 있지만 딱히 그렇지 않을 수도 있습니다. ChatGPT 같은 AI 글쓰기 도구를 활용하는 곳이 늘어난다면 그 자리는 더 줄어들 수 있구요. API 설계 초기부터 문서 작성자가 참여해야 한다는 이야기도 있는데 도메인이나 기술을 제대로 알지 못하면 소용이 없습니다. 물론 계속해서 참석하면서 쌓아갈 수는 있지만요. 당장 뭔가 내가 기여해야 한다는 압박을 가질 필요는 없습니다. OpenAPI 관련 도구들이 정리된 곳입니다. 꽤 많은 목록이 정리되어.. 환경 친화적인 문서 프레임워크 starlight라는 Astro 기반 문서 프레임워크 문서를 보다가 "환경적 영향"이라는 내용이 있어서 살펴보았습니다. 각 문서 프레임워크 방문 시 얼마나 많은 리소스를 소비하는지(탄소를 배출하는지) 측정해 보았더니 starlight가 경쟁 제품에 비해 탁월하게 환경 친화적이다라고 강조하는 내용입니다. https://starlight.astro.build/ko/environmental-impact/ Website Carbon Calculator 라는 사이트에서 간단하게 측정한 결과를 사용하고 있는데요. 이게 측정된 수치만 보면 큰 의미가 없어 보이는데 사용자 수가 수백만 인 문서 사이트를 생각해 보면 엄청난 크기가 될 수 있습니다. 문서 사이트는 텍스트 기반이라 적은 리소스를 소비할 것이라 생각하지만 프.. WTD 애틀랜틱 2023 - AI 도구를 윤리적으로 사용하려면 생성형 AI 도구를 사용해 기술 문서를 작성할 때 가장 큰 문제는 잘못된 정보(또는 허위로 작성된 정보)를 가져올 수 있다는 겁니다. 하지만 이런 문제는 AI가 아니라 잘못 작성된 사이트 정보를 참고하거나 누군가 잘못 알려준 정보를 사용할 때도 마찬가지입니다. 어떤 정보를 사용하든 이를 확인하는 책임은 문서 작성자에게 있기 때문에 이걸 윤리적인 문제라고 보는 것은 좀 애매할 듯합니다. 저작권 같은 정보도 마찬가지구요. 테크니컬 라이터가 도구를 사용해 문서를 작성하는 경우에는 그나마 중간에서 이를 확인할 수 있는 여지가 있습니다. 하지만 사용자의 질문에 답해주는 시스템을 만들었다고 생각해 보죠. 이런 경우에는 학습을 통해 고도화를 시킬 수는 있지만 답변의 내용을 하나하나 확인할 수는 없습니다(가능은 하겠지.. WTD 애틀랜틱 2023 - 스크린샷이 왜 중요한가요? launch brightly라는 솔루션을 만드는 회사의 창업자입니다. launch brightly라는 것이 제품 스크린샷을 자동으로 처리해 주는 솔루션이네요. 이번 세션은 본격 광고 세션입니다(라고 생각했는데 제품 이야기는 하지 않고 스크린샷에 대한 기본적인 이야기만 다룹니다). 독특하게 꽤 여러 회사를 창업한 후 다른 회사에 팔고 엑시트 하는 분이네요. 1996년부터 5번의 엑시트를 경험했습니다. launch brightly는 2022년 8월에 시작해서 이제 막 1년이 넘은 솔루션입니다. 아직 매각 소식은 없습니다. 세션 전반부는 왜 이미지가 중요한지 강조합니다. 뭐 다들 아는 내용이지만(사실 한국에서는 문서에 이미지를 좀 과도하게 사용하는 경향이 있고 영어권에서는 그렇지 않습니다. 가능하면 문장으로 .. 2024년 1월 테크니컬 라이팅 이런 저런 소식 1월 5일 UX 라이팅, 배민은 이렇게 시작했어요 작년 11월에 올라온 글인데 우아한테크 뉴스레터를 보다가 발견(?)했습니다. 개인적으로는 글쓴이 소개글이 맘에 드네요. "디자인으로 사고하고 글로 빚어내는 일을 해요" https://story.baemin.com/6287/ 1월 8일 개발자의 글쓰기 : Technical Writing # "사내 스터디 메이트"라는 SK 소모임에서 "Docs for Developers 기술 문서 작성 완벽 가이드" 책을 가지고 스터디하고 그 결과물을 5회에 걸쳐 블로그에 게시했습니다. 작성자가 다 다른데요. 책을 읽는 분들에게도 내용을 정리하는데 도움이 될 듯합니다. 1회(victor): https://devocean.sk.com/search/techBoardDetail... WTD 애틀랜틱 2023 - 사용자가 원하는 일을 할 수 있는 문서 만들기 발표자의 커리어가 독특한데요. 4년 정도 기자(잡지 에디터) 생활을 하고 마케팅 쪽 기술 콘텐츠를 작성하는 일을 8년간 하다가 제품 문서를 작성하는 일을 2020년부터 하게 되었다고 합니다. 학문적인 배경은 영미문학철학박사 학위를 가지고 있습니다. 이런 경험을 통해 콘텐츠에 대한 사용자의 참여를 중요하게 여기게 되었다고 합니다(아무래도 제품 문서만 만들면 사용자에 대해 민감하게 반응하지 않는데 잡지나 마케팅 콘텐츠를 다루면서 사용자에 대한 다양한 경험을 쌓았다고 강조하는 듯합니다). 대부분의 문서화 평가 지표를 보면 사용자보다는 비즈니스 측면에서 지표를 만듭니다. 때문에 그런 지표들이 사용자가 진짜 원하는 것을 가져다주는 것은 아니죠. 문서의 목적은 사용자가 원하는 작업을 빠르게 처리하고 문서를 떠나는 .. WTD 애틀랜틱 2023 - 어떻게 복잡한 기술을 쉽게 전달할까 스플렁크에 합류하고 나서 오픈텔레메트리에 대한 이야기를 PM과 했습니다. PM은 자신도 오픈텔레메트리를 이해하는데 6개월 이상이 걸렸다고 하소연을 합니다. 그럼 나(테크니컬 라이터)는 어떻게 이 기술을 이해할 수 있을까요? 오픈텔레메트리 웹사이트는 여기입니다. https://opentelemetry.io/ 나름 한국어로 된 쉬운 자료는 제니퍼소프트에서 발행한 글을 참고하세요. https://jennifersoft.com/ko/blog/tech/opentelemetry/ 하지만 이런 자료들을 테크니컬 라이터 입장에서 보면 이런 기분이라고 합니다. 이게 뭐야 싶은 거죠. 기술을 제대로 이해하려면 엔지니어의 경우에는 오랜 시간의 수련이 필요합니다. 하지만 테크니컬 라이터처럼 기술을 가지고 뭔가 하려는 것은 아.. 이전 1 2 3 4 5 6 ··· 39 다음
