Google Developers에서 진행하는 Free technical writing courses-3

Google Developers에서 진행하는 Technical Writing Two 수업에 참가하고 실습을 진행해본 글입니다. 

구글에서 2번째 수업이 진행된다고 해서 한국시간으로 새벽 4시에 참가를 해보았다. 직접 실습을 해보고 다양한 사람들의 의견을 나눌 수 있는 기회가 얼마 없다고 생각했기 때문에 새벽 이어도 꼭 듣자고 다짐했었다.🥱
결론은 듣길 잘했다. 기술문서를 작성해보면서 적용해 볼 강의 내용들도 많고 실습으로 직접 작성해보면서 조금이라도 도움이 되었다고 느꼈다. 

Technical Writing One수업과 직접적으로 연결되는 내용은 없지만 미리 사이트에서 공부를 하고 One과정을 들은 후에 Two과정을 들으니 이해가 더 잘되는 기분이랄까😁 이번에도 역시 영어로 진행이 되었지만 '구글 미트'에서는 훌륭하게 영어 자막을 제공해주기도 하고 배포되는 문서를 기반으로 실습을 진행이 되어서 크게 어려움은 없었다. 

---

Exercise 1

Group sentences into section

첫 번째 실습은 Writer가 작성한 리눅스의 하드 링크를 소개하는 글을 다듬어 보는 실습이다. 단, 글을 4개의 챕터로 나누어 제목을 부여해야 한다. 기존 문장 그대로 4개의 챕터로 나누되, 문장을 고치거나 추가하지는 않아야 한다. 

이 실습 또한 영어 번역 공부도 할 겸 한글로 우선 번역해보았다. 기존 문장은 아래와 같다. (직역)

이 문서를 읽기 전에 Linux 커맨드에 대해서 알아야 합니다. 이 문서는 소프트(symbolic) 링크가 아닌 하드 링크에 대해 많은 소개 자료를 설명합니다. 사용자가 파일을 생성하는 Linux 커맨드를 실행했다고 가정해보겠습니다. 파일을 생성했을 때, Linux는 해당 파일의 내용과 파일 이름을 만듭니다. 파일 이름은 내용에 대한 하드 링크입니다. 하드 링크는 파일 이름에서 내용에 대한 포인터입니다. 이제, 여기 흥미로운 파트가 있습니다. 사용자는 동일한 기존 내용에 대해 여러 개의 하드 링크로 만들 수 있습니다. 예를 들어, echo "Hello There." > foo라는 커맨드를 입력하면 "Hello There"라는 텍스트 내용을 포함하는 foo라는 이름의 파일을 만듭니다. In foo bar 커맨드는 foo의 내용을 가리키는 bar라는 하드링크를 만드는 방법입니다. foo와 bar를 변경하는 것은 같습니다. 사용자는 동일한 내용의 하드 링크를 여러 개 만들 수 있습니다. foo에 대한 모든 변경 사항은 bar에도 나타납니다. 

초안으로 작성된 두서없는 이 글을 4챕터로 나누어 본다면 개요/개념/예제/정리 이렇게 나눠볼 수 있지 않을까? (Linux의 사전 지식이 있는 독자를 기반으로 작성하다 보니 Linux에 대한 명령어를 덩달아 찾아보게 되었다🤔) 

4개의 챕터로 나누어서 작성해본 글은 다음과 같다. 

개요 
이 문서는 Soft(symbolic)링크가 아닌 하드 링크에 대해 설명합니다. 문서를 읽기 전 기본 Linux실행 방법과 커맨드에 대한 기본 지식이 필요합니다. 

개념
사용자가 파일을 생성하는 Linux 커맨드를 실행했을 때, Linux에서 다음을 생성합니다.

 - 파일의 내용과 파일 이름
 - 파일 이름을 내용과 연결하는 하드링크

동일한 기존 내용에 대해 여러 개의 하드 링크를 만들 수 있습니다. 

예제
다음 명령어를 호출하여 텍스트 "Hello There"를 포함하는 foo라는 파일을 만듭니다. 

echo "Hello there" > foo

다음 명령어를 호출하여 "Hello There"에 대한 bar라는 하드링크를 만듭니다. 

 In foo bar

이제 foo와 bar는 같은 의미입니다. foo에 대한 모든 변경 사항은 bar에도 나타납니다. 

정리

하드 링크는 파일 이름과 내용을 연결하는 포인터이며, 예제에 정리된 명령어를 이용해 동일한 내용의 하드 링크를 여러 개 만들 수
있습니다. 

 

나조차도 처음 작성된 초안을 읽으면서 '무슨 말이지?' 했던 글이 챕터로 나누어서 작성을 해보니 이해가 잘 된다고 느껴졌다. 테크니컬 라이터가 하는 일이 이렇게 문장의 구조를 생각하고 다시 작성하는 일이 아닐까? 당연하게도 개발자들 이기술에 이해도는 더 높겠지만 글로 설명해달라고 하면 처음 초안과 같은 상태로 주는 경우가 대다수다. 작성된 초안은 신입사원이나 다른 사용자가 봤을 때 이해하기가 어렵다.  엔지니어나 개발자가 작성한 초안을 먼저 이해하고 이를 이해하기 쉽게 바꿔주는 게 테크니컬 라이터가 하는 일이라고 생각한다. 

 

 

Excericse 2 

두 번째 실습은 다이어그램을 그려보는 실습이었다. '컴퓨터 네트워크 입문' 과정을 수강하는 학생을 대상으로 다이어그램을 그리는 것을 목표로 한다. 문서에는 이미 다음과 같은 용어가 정의되어 있다고 가정한다. 

• Top Level Domain(TLD, 최상위 도메인): 웹사이트 메인 주소 끝 (ex. ". com 또는 ". net")
• TLD Server: 지정된 TLD와 연결된 서버에 대한 정보가 있는 서버
• Root Server: TLD 서버 위치에 대한 정보가 있는 서버

추가로 문서에는 다이어그램이 놓이는 윗단 락에 아래와 같은 문장이 작성되어있다고 가정한다. 
(*쿼리는 웹 서버에 특정한 정보를 보여달라는 웹 클라이언트 요청에 의한 처리이다.)

• 클라이언트가 브라우저에 웹사이트를 쿼리 할 때마다 브라우저는 적절한 IP주소로 요청을 전달해야 합니다. 이를 위해 브라우저는 DNS(Domain Name Server)를 사용해서 IP주소를 찾습니다. DNS는 resolver를 사용해 IP 주소에 대한 정보를 여러 서버에 쿼리 합니다. 

 

위에 제공된 정보를 숙지하고 아래 문장을 다이어그램으로 작성하면 된다. 

DNS resolver가 클라이언트로부터 처음 요청을 받을 때, Root Server에게 다음에 어떤 TLD Server와 대화해야 하는지 묻습니다. Root Server는  해당 TLD Server 관련된 위치를 resolver에게 응답합니다. 

 

처음부터 작성하면 어렵기 때문에 2가지의 예시가 주어진다. 하나는 좋은 예시 그리고 다른 하나는 나쁜 예시이다. 좋은 예시이지만 여기서도 개선할 점이 있기 때문에 나는 다음과 같이 다이어그램을 그려보았다. 

Fig1. DNS가 TLD Server를 찾는 방법

나쁜 예시의 사진을 첨부하지는 않았지만 기존보다 많이 깔끔해졌고, 캡션을 사용해 이 다이어그램이 무엇을 설명하고 있는지 설명을 달아주었다.

이번 실습은 네트워크를 어느 정도 이해하고 있으면 다이어그램을 더 잘 작성할 수 있지 않을까 싶다. 가끔은 글보다 그림으로 표현하는 게 이해를 돕기가 더 쉽다. 이런 그림을 명확하게 표현할 수 있는 것도 테크니컬 라이터의 역량에 포함될 것이다. 

 

 

Excercise 3

내가 선택한 언어의 for문의 튜토리얼에 대해서 설명하는 실습이다. 필요에 따라서는 코드 블록을 사용해도 된다. 설명하는 대상은 하나 이상의 프로그래밍 언어를 알고 있지만 새로운 프로그래밍 언어를 배우고 있는 학생을 대상으로 한다. 예를 들어 C 또는 C++을 알고 있지만 지금은 Python을 배우고 있는 학생처럼 말이다. 

학생들은 이미 다음을 알고 있다고 가정한다. 

• 소스코드를 입력하고 수정하기 
• 프로그램 실행하기 
• 변수를 만들고 해당 변수에 값을 할당하기
• 변수 값과 상수 문자열을 출력하기

 

우선 나는 위 예시처럼 python(파이썬)을 선택하고 for문에 대해서 설명해보려고 한다. 구글에서 제시한 모범답안에 의견을 덧붙여 작성해보았다.  

 

여기에서는 파이썬을 처음 접하는 사람을 대상으로 for문에 대해서 설명합니다. 

예제

아래 예시 구문을 이메일로 각기 다른 다수의 사람들에게 보낸다고 가정하겠습니다. 

Dear name,
Your library book is overdue. Please retrun it.

단 두 명에게만 메시지를 보낸다면 아래와 같이 Print문을 사용해 각각의 수신자에게 보낼 수 있습니다. 

Print("Dear Lili,")
Print("Your library book is overdue. Please return it.")
Print("Dear Zuri,")
Print("Your library book is overdue. Please return it.")

하지만 만약 1000명에게 메시지를 보낸다고 가정해보면 어떨까요? 이 경우에는 반복문을 사용하는 것이 좋습니다. 반복문은 특정 코드가 반복적으로 수행되도록 하는 구문입니다. 파이썬에서 몇 가지 반복문 중에 일반적으로 많이 쓰이는 for문을 사용하면 반복적으로 예시 구문을 생성할 수 있습니다.

recipients=["Lili","Sammy","Michelle","Zuri"]
for firstname in recipints:
	print("Dear"+firstname+",")
    	print("Your library book is overdue. Please return it.")

코드의 결과는 다음과 같습니다. 

Dear Lili,
Your library book is overdue. Please retrun it.
Dear Sammy,
Your library book is overdue. Please retrun it.
Dear Michelle,
Your library book is overdue. Please retrun it.
Dear Zuri,
Your library book is overdue. Please retrun it.

 

for문 살펴보기

위의 예시를 통해 언제 for 문을 사용하면 좋을지 알아보았다면 for문의 구문을 자세히 살펴보겠습니다. 

for firstname in recipients:

이 명령문은 recipinets 목록의 각 요소와 관련된 명령문을 실행하도록 지시합니다. 예시의 경우에는 print문을 실행하도록 합니다. recipients목록에는 4개의 요소가 포함되어 있으므로 연결된 명령문을 4번 실행합니다. 반복문을 실행하면서 recipents의 다음 요소를 변수 이름에 할당합니다.

첫 번째 반복문이 실행될 때 recipients의 첫번째 요소인 Lili를 firstname에 할당한 후에 두 개의 print문을 실행합니다. 두 번째 반복문에서도 firstname에 두 번째 요소인 sammy를 할당한 다음 두 개의 print문을 실행합니다. recipients목록이 끝날 때까지 계속해서 반복문을 실행합니다. 

파이썬에서는 for문 밑에 들여 쓴 모든 문장을 실행합니다. 위 예시에서는 두 개의 명령문을 for문 밑에 들여 쓰기로 작성했습니다. 반복적으로 실행할 코드를 for문 밑에 들여 쓰기 해서 쉽게 반복문을 작성할 수 있습니다. 

 

여기까지 파이썬의 for문에 대해서 아주 간단하게 실습을 진행해보았다. 이를 바탕으로 앞으로는 개발자가 작성한 코드를 사용자 또는 전사 공유용으로 쉽게 설명할 수 있는 능력을 기를 수 있는 기회가 생기길 바란다.🔥

---

여기까지 Google Developers에서 진행하는 Technical Writing Two 강의에서 진행한 실습 내용에 대해서 정리해보았다. 처음 실습 내용을 봤을 때는 비교적 간단해 보이는데?라고 여겼었다. 그러나 강의를 진행하면서 다른 사람들의 의견을 듣고 내가 작성한 답안과 모범답안을 비교하면서 어떻게 하면 더 잘 작성할 수 있을까?를 생각하게 되었다. 

기본 개념으로만 알고 있었던 부분을 접목시켜서 실습을 진행해보니 기술 문서 작성하는 능력이 조-금 상승한 기분이 든다. 실습과정은 2에서 마무리되지만 이런 좋은 콘텐츠들이 한국에서도 많이 진행되면 좋겠다는 바람이다. 😉