"한빛N MSA"의 두 판 사이의 차이
라이언의 꿀팁백과
(새 문서: = 세미나 정보 = - 일시 : 2023년 11월 9일 7:45 ~ 9:00 - 장소 : 한빛미디어 (서울 서대문구 연희로2길 62) A동 2층 L60 - 링크 : https://festa.io/events/3819 = 문서화가 왕 = 챌린지: 사용자가 소프트웨어를 더 쉽게 사용할 수 있는 좋은 예제가 필요함 해결책: 컨트리뷰션에 고품질의 문서가 포함되도록 하기 교훈: 문서에 우선순위를 두면 사용성이 향상되고 지원 부담이 줄어듬 h...) |
(→세미나 정보) |
||
| (같은 사용자의 중간 판 9개는 보이지 않습니다) | |||
| 1번째 줄: | 1번째 줄: | ||
= 세미나 정보 = | = 세미나 정보 = | ||
- 주제 : Documentation | |||
- 강사 : 남정현 https://linkedin.com/in/rkttu | |||
- 일시 : 2023년 11월 9일 7:45 ~ 9:00 | - 일시 : 2023년 11월 9일 7:45 ~ 9:00 | ||
- 장소 : 한빛미디어 (서울 서대문구 연희로2길 62) A동 2층 L60 | - 장소 : 한빛미디어 (서울 서대문구 연희로2길 62) A동 2층 L60 | ||
- 링크 : https://festa.io/events/ | - 링크 : https://festa.io/events/4198 | ||
= 문서화가 왕 = | = 문서화가 왕 = | ||
| 17번째 줄: | 21번째 줄: | ||
https://kennethreitz.org/essays/2013/01/27/documentation-is-king | https://kennethreitz.org/essays/2013/01/27/documentation-is-king | ||
= 3 & 5 = | = 숫자 "3" & 숫자 "5" = | ||
== 3 | == 숫자 "3" == | ||
뼈대 구성 | |||
=== | === 페르소나 분석 === | ||
- 사용자가 누구일까? (독자 분석) | - 사용자가 누구일까? (독자 분석) | ||
=== | === 시나리오 분석 === | ||
- 사용자가 무엇을 할까? (행위 분석) | - 사용자가 무엇을 할까? (행위 분석) | ||
=== | === 문제점과 해결책 제시 === | ||
- 독자가 경험할 만한 어려움이 뭘까? (문제점 분석) | - 독자가 경험할 만한 어려움이 뭘까? (문제점 분석) | ||
=== 3 요약 === | === 숫자 "3" 요약 === | ||
누구를 위한 것인가? | - 누구를 위한 것인가? | ||
이 가이드로 알 수 있는 내용은 무엇인가? | - 이 가이드로 알 수 있는 내용은 무엇인가? | ||
이 가이드를 따라할 때 어떤 어려움이 있는가? | - 이 가이드를 따라할 때 어떤 어려움이 있는가? | ||
※ 사용자 가이드 뿐 아니라, 정보를 전달해야 하는 대부분의 문서, 블로그 글 등 다양한 곳에서 이와 같은 접근법으로 내용을 구성할 수 있음 | ※ 사용자 가이드 뿐 아니라, 정보를 전달해야 하는 대부분의 문서, 블로그 글 등 다양한 곳에서 이와 같은 접근법으로 내용을 구성할 수 있음 | ||
== 5 | == 숫자 "5" == | ||
글쓰기 실력 향상 스킬 | |||
=== 좋은 표현 많이 익히기 === | === 좋은 표현 많이 익히기 === | ||
| 46번째 줄: | 52번째 줄: | ||
=== 비 문학적 글쓰기 === | === 비 문학적 글쓰기 === | ||
- | - 우리가 쓰는 글은 문학이 아닌 "비문학" 이라는 것을 잊으면 안 됨 | ||
'''< | '''<비문학적 글쓰기에서 중요한 다섯 가지>''' | ||
- 숫자와 데이터 근거로 서술 | - 숫자와 데이터 근거로 서술 | ||
| 55번째 줄: | 61번째 줄: | ||
- 사물의 상태 변화를 쓸 때문 수동태, 그 외 능동태로 명확하게 서술 | - 사물의 상태 변화를 쓸 때문 수동태, 그 외 능동태로 명확하게 서술 | ||
- 핵심 문장 성분만 남기기 | - 핵심 문장 성분만 남기기 https://blog.naver.com/hard/220937869561 | ||
- 한자어, 외래어, 영어, 전문 용어는 꼭 필요할 때만 (번역체 Goodbye) | - 한자어, 외래어, 영어, 전문 용어는 꼭 필요할 때만 (번역체 Goodbye) https://tech.kakaoenterprise.com/105 | ||
- 문단 하나에 세 문장 이하로 | - 문단 하나에 세 문장 이하로 | ||
=== 일관된 글쓰기 === | |||
라이팅 스타일 = 코딩 컨벤션 | |||
- Apple Style Guide https://support.apple.com/ko-kr/guide/applestyleguide/welcome/web | |||
- Microsoft Writing Style Guide https://learn.microsoft.com/en-us/style-guide/welcome/ | |||
=== 글을 테스트하기 === | |||
- 글을 쓸 때는 집중하고, 글을 읽을 때는 편하게 마음 가는 대로 읽어보세요. | |||
- 글을 리뷰해줄 분을 찾을 수 있다면 기꺼이 받아 보시고, 답례를 잊지 마세요. | |||
- 보안에 민감한 콘텐츠가 아니라면 장소를 바꾸어서 다른 환경 속에 앉아 글을 읽어보세요. | |||
- 스마트폰에서 글을 읽거나, 종이에 인쇄해서 글을 읽어보세요. | |||
- 텍스트 확대 배율을 조금 높여서 글을 읽어보세요. | |||
=== 글쓰기를 넘어서는 정보 전달 === | |||
정보 전달의 수단 | |||
➡️ 글, 이미지, 비디오, 오디오, 인터랙티브 데모, 다이어그램 | |||
정보를 잘 전달하기 위해 고려해야 할 것 | |||
➡️ 디자인, 타이포그래피, 접근성, 가독성 | |||
➡️ 문단 배치, 들여쓰기/내어쓰기 | |||
➡️ 저작권, 문화적 요소, 다양성 존중 | |||
=== 그 외에 소소한 팁 === | |||
- 본인이 쓴 한국어 문장이 한영 번역기로 깔끔하게 잘 번역되나 가끔 확인해보기 | |||
- 데브시스터즈에는 <문서화의 날>이 있어서 이 날은 모든 일을 제쳐두고 문서화를 개선함 (다른 팀에는 양해를 구하고 수행) | |||
= 마무리 = | |||
- 업무를 객관적으로 바라볼 수 있는 방법을 알아야 함 | |||
- 세부 사항을 정리하다 보면 무엇이 문제가 되는지 쉽게 알아차릴 수 있음 | |||
- 문서를 그냥 만들면 일만 늘어남 | |||
- 따라서 문서를 만들 때는 계획에 기초해서 작성해야 함 | |||
- 비문학 글쓰기에 친해지자 | |||
'''"제품이 좋지 않으면 그것을 설명하는 문서도 좋을 수가 없습니다."''' | |||
= 질문 및 답변 = | |||
아래는 내가 질문했던 사전 질문인데 개발자 역량을 활용하며 문서화 작업을 하고 있다는 부분이 매력적이었음 | |||
'''Q) 테크니컬 라이터라서 좋은 점과 아쉬운 점을 허심탄회하게 말씀해주세요''' | |||
- 개발업무를 놓은 테크니컬 라이터가 아님. 둘 다 하는 중. | |||
- 회사에서 Material for MkDocs 로 문서 관리함 (Docker, k8s, Python 등 통해 직접 구축) https://squidfunk.github.io/mkdocs-material/ | |||
'''Q) MKDocs 고른 이유''' | |||
- MKDocs 와 MKDocs Material 을 사용하면 Markdown 에만 집중해서 사용할 수 있어서 좋았음 | |||
- Docusaurus 는 React 기반이라 좋지만 Technical Writer 입장에서는 문서작성 외 다른 부분을 신경씀 | |||
'''Q) Markdown 툴 추천''' | |||
- Typora 툴 유료로 구매해서 사용 중 https://typora.io/ | |||
= 참고사항 = | |||
강의 영상 및 발표자료는 2~3주 이내 확인 가능 | |||
[[분류:한빛미디어]] | [[분류:한빛미디어]] | ||
[[분류:MSA]] | [[분류:MSA]] | ||
2023년 11월 10일 (금) 05:47 기준 최신판
1 세미나 정보[편집 | 원본 편집]
- 주제 : Documentation
- 강사 : 남정현 https://linkedin.com/in/rkttu
- 일시 : 2023년 11월 9일 7:45 ~ 9:00
- 장소 : 한빛미디어 (서울 서대문구 연희로2길 62) A동 2층 L60
- 링크 : https://festa.io/events/4198
2 문서화가 왕[편집 | 원본 편집]
챌린지: 사용자가 소프트웨어를 더 쉽게 사용할 수 있는 좋은 예제가 필요함
해결책: 컨트리뷰션에 고품질의 문서가 포함되도록 하기
교훈: 문서에 우선순위를 두면 사용성이 향상되고 지원 부담이 줄어듬
https://news.hada.io/topic?id=11610
https://kennethreitz.org/essays/2013/01/27/documentation-is-king
3 숫자 "3" & 숫자 "5"[편집 | 원본 편집]
3.1 숫자 "3"[편집 | 원본 편집]
뼈대 구성
3.1.1 페르소나 분석[편집 | 원본 편집]
- 사용자가 누구일까? (독자 분석)
3.1.2 시나리오 분석[편집 | 원본 편집]
- 사용자가 무엇을 할까? (행위 분석)
3.1.3 문제점과 해결책 제시[편집 | 원본 편집]
- 독자가 경험할 만한 어려움이 뭘까? (문제점 분석)
3.1.4 숫자 "3" 요약[편집 | 원본 편집]
- 누구를 위한 것인가?
- 이 가이드로 알 수 있는 내용은 무엇인가?
- 이 가이드를 따라할 때 어떤 어려움이 있는가?
※ 사용자 가이드 뿐 아니라, 정보를 전달해야 하는 대부분의 문서, 블로그 글 등 다양한 곳에서 이와 같은 접근법으로 내용을 구성할 수 있음
3.2 숫자 "5"[편집 | 원본 편집]
글쓰기 실력 향상 스킬
3.2.1 좋은 표현 많이 익히기[편집 | 원본 편집]
- 많이 접하고 수집하기
3.2.2 비 문학적 글쓰기[편집 | 원본 편집]
- 우리가 쓰는 글은 문학이 아닌 "비문학" 이라는 것을 잊으면 안 됨
<비문학적 글쓰기에서 중요한 다섯 가지>
- 숫자와 데이터 근거로 서술
- 사물의 상태 변화를 쓸 때문 수동태, 그 외 능동태로 명확하게 서술
- 핵심 문장 성분만 남기기 https://blog.naver.com/hard/220937869561
- 한자어, 외래어, 영어, 전문 용어는 꼭 필요할 때만 (번역체 Goodbye) https://tech.kakaoenterprise.com/105
- 문단 하나에 세 문장 이하로
3.2.3 일관된 글쓰기[편집 | 원본 편집]
라이팅 스타일 = 코딩 컨벤션
- Apple Style Guide https://support.apple.com/ko-kr/guide/applestyleguide/welcome/web
- Microsoft Writing Style Guide https://learn.microsoft.com/en-us/style-guide/welcome/
3.2.4 글을 테스트하기[편집 | 원본 편집]
- 글을 쓸 때는 집중하고, 글을 읽을 때는 편하게 마음 가는 대로 읽어보세요.
- 글을 리뷰해줄 분을 찾을 수 있다면 기꺼이 받아 보시고, 답례를 잊지 마세요.
- 보안에 민감한 콘텐츠가 아니라면 장소를 바꾸어서 다른 환경 속에 앉아 글을 읽어보세요.
- 스마트폰에서 글을 읽거나, 종이에 인쇄해서 글을 읽어보세요.
- 텍스트 확대 배율을 조금 높여서 글을 읽어보세요.
3.2.5 글쓰기를 넘어서는 정보 전달[편집 | 원본 편집]
정보 전달의 수단
➡️ 글, 이미지, 비디오, 오디오, 인터랙티브 데모, 다이어그램
정보를 잘 전달하기 위해 고려해야 할 것
➡️ 디자인, 타이포그래피, 접근성, 가독성
➡️ 문단 배치, 들여쓰기/내어쓰기
➡️ 저작권, 문화적 요소, 다양성 존중
3.2.6 그 외에 소소한 팁[편집 | 원본 편집]
- 본인이 쓴 한국어 문장이 한영 번역기로 깔끔하게 잘 번역되나 가끔 확인해보기
- 데브시스터즈에는 <문서화의 날>이 있어서 이 날은 모든 일을 제쳐두고 문서화를 개선함 (다른 팀에는 양해를 구하고 수행)
4 마무리[편집 | 원본 편집]
- 업무를 객관적으로 바라볼 수 있는 방법을 알아야 함
- 세부 사항을 정리하다 보면 무엇이 문제가 되는지 쉽게 알아차릴 수 있음
- 문서를 그냥 만들면 일만 늘어남
- 따라서 문서를 만들 때는 계획에 기초해서 작성해야 함
- 비문학 글쓰기에 친해지자
"제품이 좋지 않으면 그것을 설명하는 문서도 좋을 수가 없습니다."
5 질문 및 답변[편집 | 원본 편집]
아래는 내가 질문했던 사전 질문인데 개발자 역량을 활용하며 문서화 작업을 하고 있다는 부분이 매력적이었음
Q) 테크니컬 라이터라서 좋은 점과 아쉬운 점을 허심탄회하게 말씀해주세요
- 개발업무를 놓은 테크니컬 라이터가 아님. 둘 다 하는 중.
- 회사에서 Material for MkDocs 로 문서 관리함 (Docker, k8s, Python 등 통해 직접 구축) https://squidfunk.github.io/mkdocs-material/
Q) MKDocs 고른 이유
- MKDocs 와 MKDocs Material 을 사용하면 Markdown 에만 집중해서 사용할 수 있어서 좋았음
- Docusaurus 는 React 기반이라 좋지만 Technical Writer 입장에서는 문서작성 외 다른 부분을 신경씀
Q) Markdown 툴 추천
- Typora 툴 유료로 구매해서 사용 중 https://typora.io/
6 참고사항[편집 | 원본 편집]
강의 영상 및 발표자료는 2~3주 이내 확인 가능