테크니컬 라이팅/WTD 컨퍼런스 (77) 썸네일형 리스트형 WTD 포틀랜드 2023 - 크라우드 소싱 방식의 문서화 프로젝트 진행하기 이번 발표에서 설명하는 Splunk Lantern이라는 프로젝트의 방식이 좀 낯설어서 전체적인 내용을 제대로 이해하지 못했습니다. 뭐 그럼에도 부족한 자원을 가지고 기여자들과 함께 문서화 프로젝트를 진행하는 여러 팁에 대해 설명하고 있는 것이라서 유익한 팁들만 받아들이면 되지 않을까 싶습니다. Splunk Lantern은 - 공식 제품 문서와 다르게 릴리스 일정과 상관없이 운영됩니다. - 커뮤니티가 아니기 때문에 누구나 문서화에 참여할 수는 없습니다. - 마케팅 지향적인 문서를 만들지 않습니다. - 기술지원 요청에 대응해서 문서를 만들지는 않습니다. Splunk Lantern은 고객을 위한 디지털 셀프서비스 가이드입니다. 현장에서 고객과 함께 일하는 엔지니어들이 자료를 만들고 고객의 성공을 돕습니다. 라.. WTD 포틀랜드 2023 - 대규모 엔지니어 조직에서 생산성 높은 문서화 프로세스 만들기 Datadog에는 12명의 테크니컬 라이터가 일하고 있습니다. 일반적인 개론에서는 1명의 테크니컬 라이터가 10~15명 정도 엔지니어와 함께 일하는 것이 이상적이라고 합니다. 미국 통계에서는 약 30명의 엔지니어를 1명의 테크니컬 라이터가 대응하고 있다고 합니다. 하지만 Datadog에서는 2000여 명의 엔지니어가 일하고 있고 12명의 테크니컬 라이터는 이들 2000여 명의 엔지니어와 매일 커뮤니케이션을 진행합니다. 물론 2000여 명의 엔지니어가 모두 테크니컬 라이터 또는 문서화에 긴밀하게 참여한다고 할 수는 없습니다. 그중에 PM이나 팀 리더와 주로 많은 작업을 합니다. 사내 엔지니어 외에도 고객, 사용자, 파트너, 기술지원, 커뮤니티, 세일즈, 번역을 담당하는 이들과도 함께 일을 해야 합니다. 이.. WTD 포틀랜드 2023 - 포용적인 언어에 대해 이번 세션 주제는 쉽지 않습니다. 발표자의 개인적인 경험을 담고 있고 여러 논쟁이 있는 주제라 그런 것 같습니다. 그래서 발표 전에 몇 가지 규칙을 미리 공지하고 진행합니다. 해당 규칙에 따라(아마 운영진과 합의된 것이 아닌가 싶습니다) Q&A는 진행하지 않았습니다. 주제는 트라우마와 포용적인 언어에 대한 이야기입니다. 트라우마라는 표현은 많이 들어보긴 했지만 실제 경험한 것이 아니라면 공감하기 쉽지는 않습니다. 한국에서는 2018년 국가트라우마센터가 설치됐습니다. 대형 재난에 대한 심리지원이 체계적으로 필요하다는 필요성 때문이었죠. 국가트라우마센터 사이트에서는 트라우마를 다음과 같이 정의하고 있습니다. https://www.nct.go.kr/itaewon/traumaIntro1.do ...트라우마란 재.. WTD 포틀랜드 2023 - 테크니컬 라이팅에 AI 활용하기 발표자는 Rokt라는 전자상거래 관련 솔루션 회사에서 테크니컬 라이터로 일하고 있습니다. 딱히 AI 관련된 기술에 가까이 있는 것은 아니고 개인적인 관심을 가지고 이런 저런 것들을 찾아보고 시도해보았다고 합니다. AI가 일상적으로 쓰인 것이 최근 일인 것 같지만 사실 검색어 입력 시 자동 완성이라든지 맞춤법 검사, 문법 검사 같은 장치들은 꽤 오래전부터 사용하고 있었습니다. 물론 이러한 것들을 의도적으로 쓰지 않는 분들도 있지만요. 기계 번역도 마찬가지입니다. 어떤 방식을 사용하든 AI가 어느 정도 개입하고 있었던 것들이죠. 테크니컬 라이터가 AI를 통해 얻을 수 있는 이점 - 생산성의 향상(반복직인 작업은 AI에게 맡기고 전체적인 문서 구조화 등 작업에 집중할 수 있음) - 콘텐츠 품질 향상(문법, 맞.. 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 문서가 담고 있어야 합니다. 틀린 내용이 없고 정확한 내용을 포함해야 합니다. 업데이트되지 않거나 오래된 문서에 대한 이야기는 다른 곳에서도 많이 들을 수 있는 이야기입니다. 개발팀과의 관계에 있어서 개발팀의 배포 기준에 문서화를 .. 이전 1 2 3 4 ··· 10 다음
