본문 바로가기
728x90

테크니컬 라이팅

 (353)
도큐사우루스에 페이지 추가하기 (2) 도큐사우루스 페이지와 문서 도큐사우루스에서는 문서와 페이지를 구분해서 설명합니다. 가장 큰 차이는 사이드바를 가지는지 여부입니다. 사이드바는 문서 왼쪽에 전체 목차처럼 표시되는 영역입니다. 문서는 책 형태를 표현하는 것이기 때문에 전체 목차를 가지고 있습니다. 페이지는 전단지처럼 별도의 목차 없이 한 페이지에 정보를 담습니다. 도큐사우루스에서는 이벤트 페이지처럼 문서와 직접 상관이 없는 항목들을 만들 때 페이지를 사용할 수 있다고 설명합니다. 도큐사우루스 사이트에서도 "쇼케이스"에 들어가면 사이드바가 표시되지 않습니다(점점 콘텐츠가 늘어나서 적절한 목차가 있어야 하지 않을까 싶긴 하지만). 상단에 필터가 있어서 원하는 콘텐츠를 필터링하는 기능을 제공하지만 사이드바에서 별도의 목차를 제공하지는 않습니다. ..
WTD 포틀랜드 2022 - 테크니컬 라이터 온보딩 프로그램으로 짝 글쓰기 활용하기 개인적인 정리 Chris Ganta는 아틀라시안 테크니컬 콘텐츠 디자이너입니다(하는 일을 보면 테크니컬 라이터와 다르지 않은데 디자인 조직 내 속하다 보니 그렇게 이름을 붙이는 것이 아닌가 싶네요). 아틀라시안에는 올해 1월 합류했고 이전에는 다양한 기업에서 테크니컬 라이터로 활동했습니다. Peer writing - "Two Heads are Better than One". And we got more than two Anyone can fall into a creative rut from time to time, but it is rare for two people to do so concurrently. 오픈소스 프로젝트에서 전문적인 테크니컬 라이터가 아닌 이들이 어떻게 문서화 작업에 성공적으로 안착..
도큐사우루스 설치하고 튜토리얼 실행하기 (1) 지난번에는 goormIDE에서 Markdoc을 설치해보았는데요. https://koko8829.tistory.com/2290 이번에는 도큐사우루스를 다루어보겠습니다. 우선 설치하고 실행하는 것까지 진행합니다. 컨테이너 생성 및 환경 설정 도큐사우루스는 Node.js 16.14 이상 버전을 필요로 합니다(2.0.0-beta.21 기준). 때문에 goormIDE에서 컨테이너 생성 시 소프트웨어 스택은 Node.js로 선택하고 추가 모듈/패키지 항목에서 "Node.js 버전 16.x로 업데이트"를 선택해야 합니다(현재 시점에서는 16.15.1로 설치합니다). 도큐사우루스 설치 도큐사우루스 공식 문서 내 "패스트트랙"이라는 항목이 있습니다. 뭐 딱히 별 내용은 없고 최초 도큐사우루스 최신 버전을 설치하고 튜토리..
WTD 포틀랜드 2022 - 구글은 문서를 어떻게 평가할까? 제목은 낚시였습니다. 정확하게 이야기하면 평가 지표 등은 오픈소스 프로젝트 조직에서 결정하는 것이고 구글은 이를 지원하는 역할만 하는 거라서~~ 개인적인 정리 Season of Docs 프로그램은 2019년 시작됐습니다. 그때는 테크니컬 라이터 Sarah Maddox와 오픈소스 담당자 Andrew Chen가 진행을 했었다고 합니다. https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html 초기에는 오픈소스 운영자에게 좋은 문서를 더할 수 있는 기회를 제공하고 테크니컬 라이터에게는 오픈소스 프로젝트에 참여할 기회를 주는 것이죠. 운영 방식 아이디어는 Summer of Code에서 가져왔는데 Summer of Code는 멘토링에 초점..
WTD 포틀랜드 2022 - Runbook과 기술 문서는 무슨 차이가 있을까? 개인적인 정리 Shane Diven는 2018년부터 Alastair Dallas는 2019년부터 Splunk에서 테크니컬 라이터로 일하고 있습니다. Splunk는 2003년 설립되어 7500명 정도가 일하고 있는데 사용자의 플랫폼을 24시간 모니터링하는 서비스를 제공하는데 문제가 생겼을 때 내부 엔지니어는 Runbook을 참조해 대응하게 됩니다. 그래서 오늘의 주제는 "Runbook"입니다. 한국어로는 적당한 번역이 없는데 IT용어대사전에서는 "실행서"라고 표현하고 있네요. 프로세스 자동화에서는 Runbook을 작업 시나리오의 의미로 사용하고 있는데 이번 세션에서는 실제 작업자가 수행해야 하는 작업 가이드라고 이해하면 될 듯합니다. 이번 세션은 이런 테크니컬 라이터를 위한 내용으로 구성했다고 합니다. A..
2022년 6월 테크니컬 라이팅 이런 저런 소식 6월 3일 Write the Docs Portland 2022 동영상이 공개됐습니다. 12개 세션, 10개의 lightning talk 영상이 포함되어 있습니다. https://www.youtube.com/playlist?list=PLZAeFn6dfHpnDhFvXG8GprqlLlzSQRBui https://www.writethedocs.org/conf/portland/2022/news/thanks-recap/ 에서 그 외 컨퍼런스 관련 정보를 확인하실 수 있습니다. 6월 8일 테크니컬 라이팅 온라인 교육 사이트가 오픈했습니다. 테크니컬 라이팅 교육과 컨설팅 서비스를 제공하는 디앤디에서 카카오 같은 재택 대상 기업에게 제공하기 위한 용도로 시작한 것이 아닌가 싶습니다. 현재는 일반 공개된 교육은 없고 특정..
WTD 포틀랜드 2022 - 문서에서 사용하는 코드를 단위 테스트하는 방법 개인적인 정리 Ben Perlmutter는 MongoDB Realm 문서 팀에서 일하고 있다고 합니다. Realm(렘)은 데이터 동기화 기술을 가진 기업으로 2019년 MongoDB에서 인수했더군요. 2017년부터 MongoDB에서 일을 시작했습니다. 간단하게 Realm이라는 것이 뭔지 설명해주며 시작합니다. 모바일 기기에 데이터를 저장했다가 서버와 동기화해주는 거라고 하네요. 요즘은 거의 모든 기기가 네트워크에 연결된 상태라 그럴 필요가 있나 싶지만 뭐 환경에 따라 그럴 수 있으니. 사이트 설명을 보면 SQLite을 대체하는 솔루션이라고 하네요. https://realm.io/ 문서 내에 포함하는 코드는 주로 사용자가 해당 코드를 복사해서 바로 사용하거나 약간의 수정 후 사용할 수 있게 구성되어 있습니..
WTD 포틀랜드 2022 - AWS 문서화팀 이야기 개인적인 정리 놀랍게도 AWS에서 2020년까지는 문서 작업을 마이크로소프트 워드 기반으로 진행했다고 합니다(일부 팀만 그렇게 했다는 건지 아니면 AWS 전체를 이야기한 건지는 명확하지 않습니다. 하지만 발표자인 Marcia Riefer Johnston가 아마존에 합류한 것이 2019년이고 Integration & Automation 팀으로 옮긴 것이 2020년 3월이라 기존에 문서를 코드처럼 다루거나 자동화하는 프로세스가 없었을 수도 있습니다). 코드 기반으로 문서를 전환한 것은 2020년 중반에 시작한 일입니다. * 개인적으로는 DOCS AS CODE가 정답이라고는 생각하지 않습니다. DOCS AS CODE의 장점을 살릴 수 있는 도구라면 대안으로 선택할 수도 있습니다. 특히 문서를 작성하는 팀이 문..
반응형

티스토리툴바