본문 바로가기

전체 글

(2559)

WTD 포틀랜드 2024 - 엔지니어링 원칙을 테크니컬 라이팅에 적용하기 컴퓨팅에서 블랙박스는 내부에서 어떤 일이 벌어지는지 몰라도 어떤 것을 입력했을 때 원하는 것을 출력할 수 있게 합니다. 하지만 엔지니어는 블랙박스에서 어떤 일이 벌어지는지 명확하게 알아야 합니다. 그리고 블랙박스에서 무슨 일이 일어나고 있는지 투명하게 설명하는 것은 테크니컬 라이터의 역할입니다.테크니컬 라이터가 블랙박스에 대해 설명하기 위해서는 많은 것을 알아야 하는데 이런 정보를 특정 엔지니어에게서 한 번에 얻는 것은 쉽지 않습니다. 대부분 조직에서 엔지니어는 자신이 담당하고 있는 일부 부분에 대한 정보만 제공할 수 있기 때문이죠. 그리고 블랙박스가 하나만 있는 것이 아니라 여러 개로 나누어져 있을 수도 있습니다. 참고: 101 things I learned in engineering school(번역..

WTD 포틀랜드 2024 - 인터랙티브한 콘텐츠 만들기 이 분은 커리어가 독특하네요. 미국과 중국, 일본에서 대학을 다녔습니다. 2008년부터 직장을 다니기 시작했는데 처음 시작한 일은 마케팅 쪽이었고 2017년에 5개월 정도의 부트캠프 과정을 거쳐 개발자로 전업을 합니다(주로 Developer Advocate 쪽 일을 했네요. 코딩을 배워서 IT 업계로 옮겼다는 것이 좀 더 정확한 표현일 것 같습니다. 하지만 중간중간 실제 개발 조직에서 일하기도 했다고 합니다). 전반부 내용은 일반적인 조언입니다. 딱히 특별한 내용은 없네요. 코드 블럭 작성 시 터미널 기호를 넣지 말라는 조언은 맘에 와닿긴 합니다. 실제로 저런 문서의 경우 복사해서 쓰고 싶은데 터미널 기호 때문에 다시 손을 대야 하거든요. 보기 좋게 하려고 줄 바꿈을 하는 명령어도 마찬가지입니다. 복사..

2024년 5월 테크니컬 라이팅 이런 저런 소식 5월 2일TCN meetup 2024.04 발표 자료 공유아래 링크에서 발표 자료를 내려받을 수 있습니다.아쉽게도 발표 영상은 제공되지 않습니다.https://rkttu.notion.site/TCN-meetup-2024-04-b65394394066453393ce107c238ecf45 5월 3일한국 테크니컬 라이터 협회 유튜브한국 테크니컬 라이터 협회 유튜브가 만들어지고 쇼츠 영상이 하나 올라왔습니다.https://www.youtube.com/@tech-writer19/featured채널 설명은 아래와 같습니다.『한국 테크니컬 라이터 협회』에서, 영문 테크니컬 라이터들이 문법 및 표현의 오류를 최소화하도록 돕고, 영어 관련 업무를 하거나 영어에 관심 있는 일반인들에게 확실한 정보를 제공하고자 만든 채널입..

땀 흘리는 운동, 매일 하면 질병 예방에 효과 없다? 관련 논문을 찾아봄 2019년 KBS 뉴스 자료입니다. 요즘에도 간혹 매일 운동하는 것이 효과가 없다는 이야기를 하면서 돌아다니는 짤입니다.출처가 그냥 "연세대보건대"라고만 나와 있어서 어떤 논문이 근거가 되는지 알 수가 없습니다. 보통 이런 뉴스는 적어도 누가 발표한 것인지 나오는데 이건 그냥 "연세대보건대"라고만 표기되어 있네요. 관련 논문 제목은 "Exercise and incidence of myocardial infarction, stroke, hypertension, type 2 diabetes and site-specific cancers: prospective cohort study of 257 854 adults in South Korea"입니다. 제목에 저렇게 숫자가 들어간 건 또 처음 보네요.https..

WTD 포틀랜드 2024 - 이미지를 적절하게 사용하기 기존의 문서는 사용자가 어디서부터 시작을 해야 하는지 이게 무슨 기술을 설명하는지 명확하게 알 수가 없었습니다. 그래서 데니스는 팀에 합류한 후 기존 문서 읽기를 포기하고 직접 기술을 다루면서 개발자들과 이야기하기 시작했습니다. 그리고 자신이 이해한 내용을 일러스트를 포함한 내용으로 작성했습니다. 데니스는 2023년에 WTD 컨퍼런스에 참여해 배운 몇몇 개념들을 실제 문서화에 반영했다고 합니다. 일러스트도 그중 하나이구요. 발표를 듣고 영감을 얻은 내용은 발표자와 좀 더 깊은 이야기를 나누었습니다. 그리고 그 결과물을 문서화에 반영한 것이죠. 튜토리얼 샘플에 대해서는 뭐 길게 이야기했지만 샘플을 제공할 때 UI와 비즈니스 로직 부분을 분리하는 것이 좋다는 것입니다. 그렇게 하면 디자이너나 개발자 모두 자..

덤벨과 아령(啞鈴) 아령(啞鈴)이라는 단어가 갑자기 낯설게 느껴져 사전을 찾아보았습니다. 아령(啞鈴) 양손에 하나씩 들고 팔 운동을 하는 운동 기구. 쇠붙이나 플라스틱 따위로 만들며, 양 끝은 공 모양으로 되어 있다. 아령은 덤벨(Dumbbell)을 그대로 직역한 한자입니다. 덤벨이라는 단어의 어원을 찾아보면 교회와 연결이 됩니다. 실제 그 시대의 Dumbbell 모습을 찾아보려 했지만 기록이 남아있지는 않다고 하네요. https://www.catholictimes.org/article/201412090108737 [일상문화 속 교회이야기] 아령 성탄에 울려 퍼지는 소리를 떠올린다면 빠질 수 없는 소리 중 하나가 종소리다. 성탄에 불리는 많은 캐럴들도 ‘징글벨’, ‘실버벨’, ‘탄일종’ 등의 가사로 성탄의 종소리를 묘사한다..

문서 내에서 URL 예시를 보여줄 때 습관적으로 dummy.com 같은 URL을 사용했는데 어떤 식으로 가상의 URL이라고 생각하고 작성해도 누군가 그것을 등록해서 사용했을 때 문제가 될 수 있기 때문에 아무것이나 사용하지 말라고 합니다. 공식적으로 문서 내에서 사용할 수 있는 도메인이 공개가 되어 있습니다. https://www.rfc-editor.org/rfc/rfc6761.html Instead, use one of the web addresses that have been designated by the Internet Assigned Numbers Authority (IANA) exclusively for use in examples. These web addresses are http://www.example.com, http:/..

2024년 4월 테크니컬 라이팅 이런 저런 소식 4월 1일What's the one word you've used most in your TW career that you never used before it?래딧 테크니컬 라이팅 채널에 올라온 글입니다. 흥미로운 질문이네요.https://www.reddit.com/r/technicalwriting/comments/1br4onr/whats_the_one_word_youve_used_most_in_your_tw 답변 중에 가장 많은 투표를 받은 단어는 "Select"인데요. "Click"이 아닌 이유는 최근의 기술 문서에서는 접근성(키보드 사용자) 또는 모바일 사용자 모두 적용할 수 있는 단어로 "Select"를 선택한다고 합니다. 그 외에도 여러 코멘트가 있으니 확인해보세요. 4월 3..

목록 더보기

티스토리툴바