테크니컬 라이팅 (353) 썸네일형 리스트형 WTD 애틀랜틱 2024 - 아랍어 현지화 경험에 대한 이야기 오픈소스는 새로운 시장으로 진출해야 하기 때문에 다른 어떤 소프트웨어보다도 현지화가 중요합니다. 현지화가 되어 있지 않으면 선택받을 가능성이 줄어들기 때문이죠. 쿠버네티스에 대한 현지화 작업은 이전에도 몇 차례 시도가 되었지만 다들 지속적인 활동으로 이어지지 못했습니다. 그러다가 올해 초 SIG-Docs 현지화 서브그룹 리더인 손석호 님이 주도해서 커뮤니티를 하나로 묶어주었습니다. 손석호 님은 ETRI 전문위원으로 다양한 오픈소스 커뮤니티에 참여하고 있고 한글화 팀을 리드하는 분이기도 합니다. 현지화 작업은 단순히 번역만 하는 것이 아니라 다양한 스태프의 참여가 필요하기 때문에 커뮤니티를 리딩하는 누군가가 필요하고 다양한 기여자가 필요합니다. 참고: SIG Docs 및 한글화 기여를 통해 쿠버네티스에 .. PNG(피엔지)와 JPEG(제이펙) 이야기 옛날 옛적, 디지털 마을에는 두 명의 화가가 살고 있었습니다. 그들의 이름은 PNG(피엔지)와 JPEG(제이펙)였어요. 두 형제는 모두 아름다운 그림과 사진을 다루는 일을 했지만, 그들은 서로 다른 방식으로 세상을 바라보고 있었습니다. 그들은 "빛의 화가"라는 불리었습니다. 그들은 빛과 색을 다루는 예술가로서, 세상의 아름다움을 다양한 방식으로 표현하는 일을 맡았어요. 하지만 두 형제는 각기 다른 도구와 기법을 사용하여 작품을 완성했습니다. 피엔지는 언제나 섬세하고 세밀한 작업을 선호했습니다. 그는 빛의 모든 색을 정확하게 표현하고, 투명한 부분까지도 완벽하게 다룰 수 있는 능력을 가지고 있었죠. 그의 작품은 언제나 선명하고, 배경이 없는 순수한 형상을 보여주었습니다. 그래서 사람들은 투명한 유리나 맑은.. SVN(서브버전)과 Git(깃) 이야기 옛날 옛적, 파일 마을에는 커다란 저장소가 있었습니다. 이 저장소는 마을 사람들 모두가 함께 사용하는 곳이었죠. 모든 사람은 자신이 만든 문서나 그림을 저장하고, 필요할 때마다 꺼내 쓸 수 있었습니다. 하지만 문제가 있었어요. 누군가가 공동으로 사용하는 문서를 수정하면, 다른 사람이 어떤 것을 수정했는지 알 수 없었고, 가끔은 실수로 중요한 파일이 덮어씌워지기도 했습니다. 마을 사람들은 혼란스러워하며 더 나은 방법을 찾기 시작했습니다. 그러던 어느 날, SVN(서브버전)이라는 지혜로운 관리자가 나타났습니다. 서브버전은 저장소에 커다란 기록 책을 만들고, 마을 사람들이 문서를 수정할 때마다 그 변화를 기록해 두었습니다. 이제는 누가 언제 무엇을 수정했는지 알 수 있었고, 실수로 파일을 덮어써도 이전 버전으.. 평온한 수호자의 전령 HTTPS 이야기 옛날 옛적, 인터넷 마을에는 폭풍의 길을 달리는 전령(HTTP, Herald of the Tempest Paths)이라는 별명을 가진 젊은 전령이 살고 있었어요. HTTP는 매우 빠르고 성실하게 정보를 전달하는 임무를 맡고 있었죠. 그는 마을 곳곳을 누비며 사람들에게 다양한 소식과 이미지를 전해주었어요. 하지만 HTTP에게는 한 가지 큰 문제가 있었어요. 그의 가방에는 자물쇠가 없어서, 누구나 그가 나르는 편지를 쉽게 열어볼 수 있었던 거예요. 어느 날, HTTP는 중요한 편지를 전하던 중 도적들에게 편지를 빼앗기고 말았어요. "이대로는 안 되겠어!" HTTP는 결심했어요. "더 이상 내 소중한 편지가 위험에 빠지게 둘 순 없어. 나는 더 강해져야 해!"라고 생각했어요. 그렇게 HTTP는 험난한 여정을 .. 워드(Word) 형제와 마크다운(Markdown) 형제 이야기 옛날 옛적, 문서 마을에서 아주 중요한 대규모 마을 역사 기록 프로젝트가 열리게 되었어요. 이 프로젝트는 마을의 모든 중요한 사건들을 문서로 남기는 일이었죠. 마을 이장님은 이 중요한 작업을 위해 마을에서 가장 유명한 두 필경사, 워드(Word) 형제와 마크다운(Markdown) 형제를 불렀어요. 이장님은 그들에게 말했어요. "이번 프로젝트는 아주 방대해서 많은 사람들의 참여가 필요합니다. 여러분들이 힘을 합쳐 이 일을 완수해 주길 바랍니다." 워드 형제는 화려한 붓과 잉크 세트를 꺼냈어요. 그들은 멋진 글씨체로 마을의 역사를 아름답게 기록하기 시작했죠. 워드 형제는 글씨를 굵게 만들고, 중요한 사건에는 색을 입히고, 표와 그림도 넣었어요. 문서를 장식하는 데에는 워드 형제만 한 사람이 없었죠. 하지만.. 레스트(Rest)와 그래프퀄(GraphQL) 이야기 옛날 옛적, 데이터 마을에는 레스트(Rest)라는 메신저가 살고 있었어요. 그는 아주 오랫동안 마을 사람들에게 필요한 정보를 가져다주는 일을 해왔죠. 레스트는 마을 사람들이 요청하는 한 가지 정보를 정해진 경로를 따라 차근차근 가져다주는 방식으로 일했어요. 예를 들어, 누군가가 사과를 원하면 레스트는 사과를 가져다주고, 배를 원하면 다시 배를 가져오는 식이었죠. 마을 사람들은 이 방식에 익숙했고, 레스트는 성실하게 일을 해왔어요. 그러던 어느 날, 그래프퀄(GraphQL)이라는 새로운 메신저가 마을에 나타났어요. 그래프퀄은 특별한 능력을 가지고 있었는데, 한 번에 여러 가지 정보를 가져올 수 있는 마법 같은 힘을 가지고 있었죠. 사람들이 "사과와 배를 함께 가져다 주세요!"라고 말하면 그래프퀄은 한 번에.. WTD 애틀랜틱 2024 - GraphQL 문서를 좀 더 풍성하게 만들기 GraphQL을 사용하면 Introspection을 활용하면 API 문서를 자동으로 생성할 수 있습니다. 하지만 기본 제공되는 문서화 기능만으로는 독자가 맥락을 파악하고 손쉽게 원하는 정보를 얻을 수 없습니다. 때문에 다양한 도구를 사용해서 독자가 정보를 탐색할 수 있게 합니다. 테크니컬 라이터가 별도의 기술 지원을 받지 않고도 GraphQL Playground나 GraphiQL 같은 것을 사용해 기본 문서에 인터랙티브한 기능을 더하고 독자들에게 필요한 정보를 제공할 수 있습니다. 모범적인 사례로 shopify를 보여줍니다(아마 shopify는 자체 개발을 통해 기능을 구현한 것으로 보입니다. 뒤에서 설명하는 발표자의 highnote 사례와는 좀 다릅니다). shopify의 경우 API를 한 페이지에 .. WTD 애틀랜틱 2024 - 코드 기반 다이어그램 사용하기 kong 문서 팀은 6명으로 구성되어 있습디다. 5명의 테크니컬 라이터와 1명의 도큐먼트 엔지니어가 일하고 있습니다. 이 팀에서 13명의 PM과 150여명의 개발 엔지니어. 30여명의 지원 엔지니어와 함께 문서화 작업을 진행합니다. 문서 팀에서 다루어야 할 업무가 점점 많아지고 있어서 가능한 반복적인 작업은 자동화할 수 있도록 노력하고 있습니다. 그 중 하나가 다이어그램이었습니다. 다이어그램을 위해 사용하는 프로그램은 한 가지가 아니었습니다. Figma, Miro, Lucidchart, draw.io 같은 도구를 사용하고 있었습니다. 그리고 그 외에 다른 도구를 사용하기도 했습니다. https://www.figma.com/resource-library/diagramming/https://miro.com/.. 이전 1 2 3 4 5 ··· 45 다음
