테크니컬 라이팅 (353) 썸네일형 리스트형 WTD 포틀랜드 2023 - 데이터 기반으로 문서 관리하기 두 명이 세션을 진행하는 경우는 흔한 건 아닌데 Alex는 테크니컬 라이터이고 Lauren은 분석가입니다. 주제가 데이터를 기반으로 문서 관리하기이기 때문에 어떤 식으로 데이터를 분석하고 이를 콘텐츠 유지 관리에 반영했는지 설명합니다. 아쉬운 것은 발표하는 내용이 자신의 분야에 딱 맞아떨어지는 건 아닌 것 같고 좀 애매하게 섞여 있어서 정신이 없긴 하네요. 지금은 DigitalOcean이라는 클라우드 컴퓨팅 기업에서 일하고 있습니다. 유지 관리 대상을 두 가지로 구분하고 있습니다. 하나는 정기적으로 점검해야 하는 기존 콘텐츠이고 하나는 문서화되지 못한 것을 발견하고 만들어야 하는 콘텐츠입니다. 정기적인 점검은 18개월 기준으로 업데이트되지 않는 콘텐츠를 찾고(이때 구글 Looker를 사용한다고 합니다) .. WTD 포틀랜드 2023 - 규범주의와 기술주의 음. WTD에서 이런 주제를 다루다니요. 워낙 다양한 배경을 가진 분들이 참여하다 보니 그럴 수 있습니다(Ed도 대학에서 언어학을 가르치다가 테크니컬 라이터로 최근에 일하기 시작했다고 합니다). 일단 Descriptivism(기술주의) 技術이 아니라 記述이라고 합니다. 그 반대(상대)적인 개념은 Prescriptivism(규범주의)이구요. 언어 변화에 대해 옳고 그름을 규정할 것인지(규범주의), 쓰이는 것을 모두 포괄할 것인지(기술주의) 이렇게 구분할 수 있습니다. 언어규범은 사회적으로 언어에 대해 옳다고 여겨지는 형식이고 예를 들면 맟춤법, 사전 등을 들 수 있다고 합니다. 주로 영어에 대한 이야기라 한국어 기준에서는 좀 애매할 수 있는데 테크니컬 라이터로서 언어규범을 어떻게 적용해야 할지 결정하는 것.. WTD 포틀랜드 2023 - 이미지를 적절하게 사용하기 Caitlin은 주로 교육(개발자 교육) 업무를 담당하다가 몽고DB 문서팀에 합류하게 되었다고 합니다. 이전에 교육 과정 개발 등의 일을 했던 경험이 있어서 학습 이론에 따라 사용자가 정보를 좀 더 쉽게 인지할 수 있게 이미지를 적절하게 사용하는 방법을 소개합니다. 뭐 특별한 내용이 있는 것은 아니고 기본적으로 알고 있는 내용들입니다. 복잡하게 설명한 문장을 간단한 이미지 하나로 설명할 수 있다든지, 이미지(특히 구조도 같은)를 작성할 때 일관성을 유지한다든지, 텍스트에 하이라이트를 추가하거나 선에 색상을 추가하는 등의 작업이 필요합니다. 예를 들면 아래와 같은 텍스트를 When you want to connect to an API, the first thing you need to do is ident.. WTD 포틀랜드 2023 - 자동화가 다 좋은 건 아닙니다 Dan은 엔지니어링 배경을 가지고 있으며 여러 분야에서 일을 하다가 지금은 소프트웨어 쪽에서 일하고 있고 문서 작성 특히 API 문서화 관련된 일을 하고 있습니다. API 문서화와 관련해서 다음과 같은 목표를 가지고 있습니다. - 일관성: 누가 어디서 작성을 하든 조직 내 API 문서는 같은 형식으로 작성되고 배포되기를 원합니다. 특히 마이크로 서비스 아키텍처인 경우 각 서비스를 개발하는 조직이 달라지면서 일관성을 잃어버릴 수 있습니다. - 명확성: 최신의 코드 정보를 API 문서가 담고 있어야 합니다. 틀린 내용이 없고 정확한 내용을 포함해야 합니다. 업데이트되지 않거나 오래된 문서에 대한 이야기는 다른 곳에서도 많이 들을 수 있는 이야기입니다. 개발팀과의 관계에 있어서 개발팀의 배포 기준에 문서화를 .. WTD 포틀랜드 2023 - 연구자의 글쓰기 대부분의 연구소에서는 문서를 작성하기 위한 전담자가 없고 연구 담당자가 문서를 작성해야 하는데 자신의 업무 중 10% 미만의 시간을 들인다고 합니다. 제목에서 SOP는 표준작업지침서(Standard Operating Procedure)의 약자라고 하네요. 구글 검색에서 SOP라고 찾아보면 무슨 규약 같은 느낌으로 작성되어 있던데 발표자가 이야기하는 것과 같은 것인지는 모르겠습니다. 아마도 실험을 진행하기 전에(새로 합류한 연구원인 경우) 꼭 읽어야 하는 문서라고 하니 맞을 것 같습니다. 하지만 실제 조사를 해보면 SOP를 읽는 비중은 46:53이라고 합니다. 53%는 읽지 않는다는 것이죠(뒤에서 언급하긴 하지만 읽는 것을 확인하는 절차는 있습니다). SOP는 새로운 장비의 영향을 받습니다. 새로운 장비가.. 2023년 7월 테크니컬 라이팅 이런 저런 소식 7월 4일 채널 박재호 유튜브에 "Docs for Developers 기술 문서 작성 완벽 가이드" 소개 영상이 올라왔습니다. 아직 책을 읽어보지 못한 분들은 영상을 먼저 보시고 어떤 내용을 다루는지 살펴보는 것도 좋을 것 같네요. 번역서에는 11명의 테크니컬 라이터 인터뷰가 실려있는데 꽤 깊은 내용까지 다루고 있습니다. 그 내용만 따로 정리해도 좋을 것 같더군요. https://jhrogue.blogspot.com/2023/07/docs-for-developers.html 7월 5일 MDN에 AI Help 기능이 추가됐습니다. 공식 블로그에 올라온 건 6월 27일이네요. MDN 플러스 회원들에게 제공되며 무료 회원인 경우에는 5번, 유료 회원은 무제한 질문이 가능하다고 합니다. https://devel.. WTD 포틀랜드 2023 - 문서의 '릴리스 레디'는 어떤 상태인가요? 문서화에서 '릴리스 레디'라는 표현은 제품 릴리스 후 24시간 내에 모든 문서와 번역이 완벽하게 완료될 수 있다는 것을 의미합니다. 어찌보면 당연한 거 아닌가 싶기도 한데 제품과 문서가 같은 프로세스를 따라 배포되지 않는다면 문제가 되는 부분이라는 것을 알 수 있습니다. 문서를 코드처럼 다루기랑 비슷한 주제죠. 그래서 이번 발표에서는 안정된 프로세스가 없더라도 '릴리스 레디' 문서 프로세스를 만들 수 있는 팁을 제시합니다. (1) 뭐가 바뀌는지 알기 - 제품팀과 긴밀한 관계를 가지고 계속 커뮤니케이션하는 것이 중요합니다. 궁금한 것은 바로 물어볼 수 있어야 하고 어느 정도의 가시성(신규 개발 일정)을 확보해야 합니다. (2) 규모 확인하기 - 릴리스마다 항상 같은 비중으로 문서가 작성되는 것은 아닙니다... WTD 포틀랜드 2023 - 테크니컬 라이터로 경력을 이제 막 시작하려는 이들을 위한 여러 조언들 개인 블로그를 통해 10명의 테크니컬 라이팅 관련 업무를 하는 현업을 대상으로 인터뷰를 진행했습니다. 인터뷰 대상을 테크니컬 콘텐츠 크리에이터라고 표현하고 있습니다. https://www.everythingtechnicalwriting.com/tag/interviews/ 인터뷰의 목적 중 하나는 성공한 이들이 어떤 과정을 거쳐서 지금의 자리에 올라왔는지 소개하고 시작하는 이들이 이런 실수를 피할 수 있게 하려는 것입니다. 그리고 어떻게 시작해야 할지 감을 잡을 수 있게 하려는 것이지요. 테크니컬 라이터를 시작하려는 이들이 얻을 수 있는 정보는 어느 곳이나 그렇지만 매우 적습니다. 일부 국가에서는 테크니컬 라이팅 전공이 있는 경우도 있지만 대부분 그렇지 않고 학원 시장에서도 엔지니어 중심의 교육이 이루어지.. 이전 1 ··· 9 10 11 12 13 14 15 ··· 45 다음
