brunch

매거진 브런치 개발자들의 이야기

라이킷 12 댓글 1

You can make anything
by writing

C.S.Lewis

계정을 잊어버리셨나요?

by 웅쓰 May 26. 2022

테크니컬 라이팅 레벨업

그냥 쓰는 거 같아도 이게 다..!

안녕하세요. iOS 개발하는 웅쓰입니다.

한 달을 건너뛰었더니 굉장히 오랜만에 글을 쓰는 것 같습니다.

요즘 바쁜 하루하루를 보내고 있는데요, 그중에 테크 커뮤니케이션 관련 주제로 사내 교육을 듣고 있습니다. 글을 어떻게 써야 하는지, 말은 어떻게 해야 하는지 등등 정말 많은 걸 배우고 있어요. 오늘은 교육 과정 중 있었던, 예전에 제가 작성한 기술 문서를 가져가 첨삭을 받았던 내용에 대해 공유드려보고자 합니다.

이제 저는 배운 사람이니 목차도 한번 만들어봤습니다.

0. 들어가기
  - 무엇을 위한 글인가.
  - 누가 읽을 것인가.
1. 무엇을 작성할 것인가. 목차 구성, 뼈대가 튼튼하면 쌓는 건 쉽다.
  - AS-IS
  - 개선 1. 제목에 대한 설명이 먼저 나오면 좋다.
  - 개선 2. 각 항목은 제목과 유기적으로 연결되어야 한다.
  - 개선 3. 불필요한 중복을 피하자.
  - 개선 4. 애매한 표현을 제거하자.
  - TO-BE
2. 어떻게 표현할 것인가. 채워 넣기.
  - 개선 1. 모호할 바엔 길어도 정확하게
  - 개선 2. 이미지는 거들뿐. 글이 기본이다.

0. 들어가기

본 수업은 '기술 문서'만을 대상으로 하고 있었기에 이어질 내용도 기술 문서에 한정된 내용일 수 있습니다 :)

이 수업은 실제로 강사님께 첨삭을 받아야 했기에 기술 문서와 문서의 유형과 문서의 대상을 생각해서 갔어야 했습니다. 준비과정부터 그동안 뭔가 잘못됐다는 느낌을 받을 수 있었습니다. 글의 유형을, 대상을 염두에 두고 작성한 적이 없었기에...

무엇을 위한 글인가.

제가 가져갔던 기술 문서는 [Post RIB] 였는데요. 저희 코드에 적용되어 있는 uber RIBs의 RIB들을 정리하고 있는 문서입니다. 유형을 나누자면 설명문이라고 할 수 있습니다. 지금 자세한 이론을 다룰 건 아니지만, 앞으론 내가 어떤 성격의 글을 쓰는지 '생각'하며 작성해야겠다는 걸 배웠습니다.

누가 읽을 것인가.

그동안은 문서의 대상도 마찬가지로 그동안은 고려하지 않았습니다. 기술 문서인 만큼 대상의 수준이 어떤지, 같은 배경을 공유하고 있는 팀원을 위한 글인지를 외부인에게 공유하는 건지도 '생각'하며 작성해야겠다는 것도 배웠습니다.

1. 목차 구성. 뼈대가 튼튼하면 쌓는 건 쉽다.

처음 피드백 대상은 목차였습니다.

목차는 글의 뼈대를 세우는 일이다. 글을 쓸 때는 목차부터 잘 작성해야 하고 사실상 이게 전부다. 목차를 잘 만들었다면 다음은 그대로 내용을 채워 넣기만 하면 된다. 목차는 독자가 빠르게 찾고 이해하기 쉽도록 각각의 내용이 논리적으로 연결되어야 한다.

위와 같이 주옥같은 말씀들을 많이 해주셨고 구체적인 피드백이 이어졌습니다.

AS-IS

기존 목차는 다음과 같았습니다.

제목: [Post RIB]
- 주요 화면
- RIB Tree
- 주요 기능
- 기능 상세
- Post 요청
- Post Password 업데이트

혹시 위 구성만 봤을 때 문제점들이 보이시나요? ~~그렇다면 당신은 이미 고수... ;)~~

목차만 놓고 보아도 크게 4가지 정도 개선 포인트가 있었습니다.

개선 1. 제목에 대한 설명이 먼저 나오면 좋다.

처음으로 받은 피드백은 제목이 [Post RIB]이라면 Post RIB이 무엇인지에 대한 설명이 먼저 나오면 좋다는 내용이었어요. 대상은 Post RIB을 잘 모르는 사람을 대상으로 해놓고 작성할 때는 무의식적으로 이미 어떤 건지 알고 왔다는 전제가 깔려 있었던 거죠. (사실 작성할 때는 명확히 정해두지도 않았었습니다...)

제 글에서 'Post RIB이 무엇인지에 대한 설명'은 RIB Tree 부분에 있었고, 둘의 순서를 바꿨습니다. 순서를 바꾸고 나니 다음 문제가 보였습니다.

개선 2. 각 항목은 제목과 유기적으로 연결되어야 한다.

두 번째 문제는 RIB Tree라는 말이 굉장히 애매하다는 것이었습니다.

"강사님: RIB Tree가 뭘 말하는 걸까요?"

"나 : 아! RIB Tree 중에서 Post RIB에 진입하고 이동할 수 있는 부분을 의미하는 거예요!"

"강사님: 그럼 그렇게 써주시면 좋겠네요!"

"나 : ...!!!"

RIB Tree라는 말 자체가 포함하는 범위가 넓다 보니 모호하게 해석될 여지가 많았습니다.

- 이어질 내용이 전체 RIB Tree라는 걸까요? (그렇다면 왜 [Post RIB]에..?)

- RIB Tree가 Post RIB이라는 걸까요?

- RIB Tree에서 Post RIB이라는 건가요?

이렇게 다양하게 해석될 수 있겠죠. 제 의도는 세 번째였는데 말이죠...

빠르게 Post RIB으로 수정하고 강사님께 설명드린 내용을 밑에 적어주었습니다.

개선 3. 불필요한 중복을 피하자.

다음 피드백은 "주요 기능과 기능 상세는 사실상 같은 항목으로 볼 수 있지 않을까요?"였습니다. 생각해보면 당연한데요. 제목이 '기능'이라면 당연히 그 안에는 기능의 세부 내용이 들어갈 테니까요. 특별한 이유가 없다면 굳이 나눌 필요가 없습니다.

개선 4. 애매한 표현을 제거하자.

다음 피드백은 '주요'라는 표현이 굉장히 애매할 수 있다는 것이었어요.

'주요'라는 단어를 봤다면 독자에게는 최소 두 가지 의문이 생깁니다.

'주요' 기능이 있다면 아닌 일반적인 기능은 뭘까요?
왜 그 기능이 주요한가요?

적어도 이 두 가지에는 확실히 답을 할 수 있어야겠죠..!

그래서 빠르게 '주요' 부분을 제거했습니다.

TO-BE

위 피드백을 반영해 아래와 같이 목차를 개선했습니다.

전보단 더 깔끔해졌나요??

제목: [Post RIB]
1. Post RIB
2. Post RIB 화면
3. 기능
3.1 Post 요청
3.2 Post Password 업데이트

2. 채워 넣기.

앞서 목차를 잘 만들었다면 이제 적절하게 내용을 채워나갈 차례입니다.

개선 1. 모호할 바엔 길어도 명확하게

기존에 제가 작성했던 글에선 모호한 부분들이 있었습니다. 앞서 목차 개선 2 부분에서 잠깐 나온 것처럼 생략된 부분들이 많이 있었는데요, 처음 RIB Tree는 이렇게 생겼었습니다.

RIB Tree

지금 보니 살짝 너무 했다는 생각도 듭니다... 심플한 그림이라 "보면 알겠지"라는 생각이 있었던 것 같아요.

첫 피드백을 받고 다음과 같이 수정했습니다. (이후 그림은 생략합니다)

RIB Tree

Post RIB에 진입하고 이후 이동할 수 있는 계층 관계를 설명합니다.
- [진입] PostId, PostStringId를 주입받아 진입합니다.
- 일반 글: PostId / 공지 글: PostStringId (slogan 관련 코드에 사용됩니다.)
- Post 요청 설명 참고
- [이동] 그림과 같이 다양한 경로로 이동할 수 있습니다.

설명이 없는 것보단 나아졌지만 아직 애매한 부분이 존재합니다.

slogan 관련 코드는 공지글에 사용된다는 걸까요? 일반 글, 공지 글 둘 다 사용된다는 걸까요?

또 Post 요청 설명에는 어떤 내용이 들어있었다는 건지도 애매합니다.

그리고 경우의 수가 명확하다면 다양한 보다는 정확한 개수를 적어주는 게 좋다,

그렇게 개수를 명시했다면 이어서 거기에 대한 설명이 따라오는 게 자연스럽다는 피드백도 받았습니다.

피드백 이후 최종적으로 다음과 같이 개선했습니다.

RIB Tree

Post RIB에 진입하고 이후 이동할 수 있는 계층 관계를 설명합니다.
- [진입] PostId, PostStringId를 주입받아 진입합니다.
  - 일반 글: PostId
   - 공지 글: PostStringId
     slogan 관련 코드에 사용됩니다.
    slogan 관련 내용은 Post 요청 설명 참고
- [이동] 그림과 같이 6개의 경로로 이동할 수 있습니다.
  - Blog RIB: ~~~
  - ...

조금 더 나아졌을까요?!

개선 2. 이미지는 거들뿐. 글이 기본이다.

'글이 기본'이다. '그림은 부수적인' 도구일 뿐이다.

이건 제가 궁금했던 부분들을 질문하고 답변을 받다가 나온 내용인데요. 제게 너무 필요하고 와닿았던 가르침(?)입니다. 기존에 저는 그림, 도표 등으로 많은 걸 표현해보려고 여러 시행착오를 겪고 있었는데요.

"항상 글이 디폴트다. 그림은 보는 사람마다 다 다르게 해석할 수 있기 때문에 그림이 없어도 글만 보고 설명이 다 되어야 한다."라고 말씀을 해주셨는데 이 부분이 너무 많은 도움이 되었습니다.

----

RIB 정리를 하면서 어떤 식으로 정리하면 좋을지 나름의 판단이 서지 않아서.. 이렇게 저렇게 정리해보며 매번 시간이 많이 걸렸었는데요, 위 내용대로 개선하고 제일 좋았던 건 이제는 다른 RIB들도 똑같이 정리할 수 있게 되었다는 점이었습니다.

본문의 글 말고 다른 RIB도 하나 더 가져갔었는데요, 복사 붙여 넣기가 가능한 구조가 되어서 기뻐하는 절 보며 강사님이 "그거예요! 좋은 글은 가져다가 거기에 맞게 조금씩만 바꿔주면 되는 거예요!!"라고 맞장구 쳐주셨고 그렇게 훈훈하게 마무리를 할 수 있었습니다. :]

본문의 일은 저번 주였지만, 전체 과정이 오늘로 드디어 마무리가 되었어요! 진짜 많이 배웠고 유익한 시간이었습니다. 요즘 오고 가며 이윤규 변호사님의 글 읽기 관련 유튜브들을 많이 보고 있는데요. 글을 쓰면서 잘 쓰는 것과 잘 읽는 방법이 참 많이 닮아있다는 생각이 들었습니다. 결국 잘 읽히게 쓰는 것이니 당연한 걸까요..ㅎ

또 관련 있는 내용만 넣고 중복을 제거하고 명확하게... 좋은 글은 좋은 코드와도 참 많이 닮아있다는 생각이 들었습니다. 이래저래 잘하기란 참 어렵네요 ;ㅅ;

수업 관련 내용이 처음 공유될 때 노아가 하신 말씀이 생각이 납니다. "들을 땐 별거 아닌 거 같아도 이런 게 쌓여 나중엔 차이를 만든다." 한 번 들어서 다 이해하고 완벽하게 적용하긴 어렵겠지만 확실히 어제보단 발전했겠죠?

읽어주셔서 감사합니다!