본문 바로가기

728x90

테크니컬 라이팅/WTD 컨퍼런스

(117)
WTD 포틀랜드 2024 - 제품 내 도움말은 정말 도움이 되는가? 동영상 제목과 별개로 발표의 제목은 "Creating contextual content experiences"입니다. IBM에서 일하던 시절(2003년부터 2020년까지) Michael Priestley, Don Day 같은 DITA 교과서에 나오는 분들과 같이 일했다고 합니다. 지금은 "Automation Anywhere"라는 회사에서 DITA 자동화 관련 작업을 하고 있다고 합니다. 중간에 뭔가 통합했다는 뭐 그런 이야기가 나오는데 "Zoomin for Pendo"라는 제품인가 봅니다. 내부적인 요구사항에 대해 솔루션을 선택했고 이를 통합해서 제공한다는 뭐 그런 이야기입니다. 그 과정에서 이러이러한 어려움이 있었고. 뭐. 그런 이야기죠.https://www.zoominsoftware.com/zoomi..
WTD 포틀랜드 2024 - R&R을 통해 한 단계 높은 성과 만들기 Calvin Fung는 경력이 화려합니다. 딱 엘리트 코스를 따라갔습니다. 졸업하기 전에 마이크로소프트에서 1년간 인턴을 하고 5년간 정규직으로 일을 시작합니다. Operation specialist(지원팀에 가깝다고 합니다. 한국어로는 딱 명확한 번역이 애매하네요)로 일했는데 그다음 커리어는 테슬라에서 테크니컬 라이터로 일을 하게 됩니다. 그리고 AWS로 옮겨서 테크니컬 라이터, 테크니컬 아카데미, 엔지니어들의 역할을 가지고 일을 했습니다. 때문에 이번 강연에서 이야기하는 레벨업의 수준이 좀 맞지 않을 수도 있을 겁니다(라고 생각했는데 그렇게 디테일하게 들어가지는 않네요). R&R은 의무적으로 작성하긴 하지만 이를 제대로 활용하지는 못합니다. R&R에서 할 수 있는 일의 단계를 구분하고 내가 얼마나 성..
WTD 포틀랜드 2024 - 문서화는 봄날의 햇살입니다. 좀 더 자세한 이야기. "2022 데브옵스 현황 보고서 데이터 심층 분석: 문서화는 봄날의 햇살입니다"와 관련된 세션입니다.https://koko8829.tistory.com/2413 연구 결과에 대해 간단하게 설명하는 자리였구요. 일단 해당 문서는 외부에 공개되는 기술 문서가 아니라 조직 내부에서 사용하는 기술 문서에 대한 연구였다고 합니다(좀 설명이 애매하긴 한데). 엔지니어들이 자신의 팀에서 관리하는 기술 문서가 개발 프로세스에 어떻게 영향을 주는지 확인하는 작업이었다고 합니다. 2023년 보고서까지 공개가 되어있구요. 2024년 서베이가 진행되고 있습니다. 주로 북미 쪽에서 나온 답변을 위주로 작성된 보고서이기 때문에 문화적인 차이에 따라 다를 수 있습니다.  문서 품질과 관련된 8개 속성과 관련된 질문이라고 합니다. ..
WTD 포틀랜드 2024 - 여러 버전의 문서를 공개했을 때 검색이 안되는 문제 해결하기 DX 엔지니어이고 문서화에 필요한 엔지니어링 작업을 합니다. 테크니컬 라이터와 같이 왔다고 소개하는데 아마도 Christina Ausley를 이야기하는 것 같네요. 인상적인 것은 프레젠테이션 자료를 수채화처럼 직접 그려서 작성했습니다(이렇게 그려주는 도구가 있을지도 모르겠으나, 그림체로 보면 직접 그린 것이 맞습니다). 7 버전(C7)은 Hugo 기반으로 작성됐는데 8 버전(C8)으로 올리면서 전반적인 문서의 내용이 변경됐고 문서화 플랫폼도 도큐사우르스로 바꾸었다고 합니다. 문서팀은 4명으로 구성되어 있는데 3명이 테크니컬 라이터이고 1명이 엔지니어입니다.  문서화 플랫폼을 바꾼 이유는 검색 품질 때문이었다고 합니다. 2021년 초에는 "BPMN"이라는 키워드에 대해 20개의 결과가 나왔다면 점점 줄어들..
WTD 포틀랜드 2024 - 엔지니어링 원칙을 테크니컬 라이팅에 적용하기 컴퓨팅에서 블랙박스는 내부에서 어떤 일이 벌어지는지 몰라도 어떤 것을 입력했을 때 원하는 것을 출력할 수 있게 합니다. 하지만 엔지니어는 블랙박스에서 어떤 일이 벌어지는지 명확하게 알아야 합니다. 그리고 블랙박스에서 무슨 일이 일어나고 있는지 투명하게 설명하는 것은 테크니컬 라이터의 역할입니다.테크니컬 라이터가 블랙박스에 대해 설명하기 위해서는 많은 것을 알아야 하는데 이런 정보를 특정 엔지니어에게서 한 번에 얻는 것은 쉽지 않습니다. 대부분 조직에서 엔지니어는 자신이 담당하고 있는 일부 부분에 대한 정보만 제공할 수 있기 때문이죠. 그리고 블랙박스가 하나만 있는 것이 아니라 여러 개로 나누어져 있을 수도 있습니다. 참고: 101 things I learned in engineering school(번역..
WTD 포틀랜드 2024 - 인터랙티브한 콘텐츠 만들기 이 분은 커리어가 독특하네요. 미국과 중국, 일본에서 대학을 다녔습니다. 2008년부터 직장을 다니기 시작했는데 처음 시작한 일은 마케팅 쪽이었고 2017년에 5개월 정도의 부트캠프 과정을 거쳐 개발자로 전업을 합니다(주로 Developer Advocate 쪽 일을 했네요. 코딩을 배워서 IT 업계로 옮겼다는 것이 좀 더 정확한 표현일 것 같습니다. 하지만 중간중간 실제 개발 조직에서 일하기도 했다고 합니다). 전반부 내용은 일반적인 조언입니다. 딱히 특별한 내용은 없네요. 코드 블럭 작성 시  터미널 기호를 넣지 말라는 조언은 맘에 와닿긴 합니다. 실제로 저런 문서의 경우 복사해서 쓰고 싶은데 터미널 기호 때문에 다시 손을 대야 하거든요. 보기 좋게 하려고 줄 바꿈을 하는 명령어도 마찬가지입니다. 복사..
WTD 포틀랜드 2024 - 이미지를 적절하게 사용하기 기존의 문서는 사용자가 어디서부터 시작을 해야 하는지 이게 무슨 기술을 설명하는지 명확하게 알 수가 없었습니다. 그래서 데니스는 팀에 합류한 후 기존 문서 읽기를 포기하고 직접 기술을 다루면서 개발자들과 이야기하기 시작했습니다. 그리고 자신이 이해한 내용을 일러스트를 포함한 내용으로 작성했습니다. 데니스는 2023년에 WTD 컨퍼런스에 참여해 배운 몇몇 개념들을 실제 문서화에 반영했다고 합니다. 일러스트도 그중 하나이구요. 발표를 듣고 영감을 얻은 내용은 발표자와 좀 더 깊은 이야기를 나누었습니다. 그리고 그 결과물을 문서화에 반영한 것이죠. 튜토리얼 샘플에 대해서는 뭐 길게 이야기했지만 샘플을 제공할 때 UI와 비즈니스 로직 부분을 분리하는 것이 좋다는 것입니다. 그렇게 하면 디자이너나 개발자 모두 자..
WTD 호주 2023 - 라이트닝 토크 모음 Lightning Talk: Alec Clews - One Word Trick to Automate docs as code 보통 클라우드에서 작업할 때는 뭔가 피드백이 늦게 발생합니다(작업 환경에 따라 다르지만). 그래서 Git 클라이언트에서 사용할 수 있는 Git Hook 옵션을 제안합니다. 발표자료: https://docs.google.com/presentation/d/e/2PACX-1vSE_oFHfPPC8SuP0Nqvco6om2kLCX7DUDkKC_pqHdfcY7He7n5IBLPbZmj1yOlzDIJa9a_m6uAruRa1/pub?slide=id.p 데모: https://gitlab.com/alecthegeek/docs-as-code https://youtu.be/K-T0u-nIaOc?si=-JTc..

반응형