📝 김철수님의 '개발자의 글쓰기'를 읽고 정리한 글입니다. 문제가 될 경우 삭제 조치하도록 하겠습니다.

1. 서비스 개념을 범주, 용도, 특징으로 설명하자

1.1 범주, 용도, 특징

서비스 매뉴얼이나 개발 가이드의 첫 문단은 서비스의 개념을 설명해야 한다. 독자들은 서비스 개념을 확실히 하지 않으면 이후에 나오는 내용들을 이해할 수가 없다.

개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 게 좋다.

1. 독자가 잘 아는 범주를 먼저 말하면 안심하면서 해당 범주 떠올림
2. 그 범주의 용도를 말하면 독자는 자연스레 서비스의 용도와 같음을 알아챔
3. 그 범주 내의 유사 서비스와 차별화 특징을 말하면 독자는 서비스의 개념을 정확히 이해

이렇게 개발자만 아는 것부터 다짜고짜 먹어보라고 보여주는 것보다 독자가 이미 아는 내용들로 보여주면서 천천히 설명해 나가는 방법이다.

[AWS 예시]

(범주) : Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.
(용도) : Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 우너하는 양의 데이터를 저장하고 검색할 수 있습니다.
(특징) : AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.

1.2 범주를 정확하고 적절하게 선택하자

AWS는 Amazon S3의 범주를 독자에게 익숙한 인터넷 스토리지 서비스 로 정의한다. 여기서 알아야 할 점은 이미 독자가 가진 범주를 사용함으로써 서비스의 개념을 간단하고 정확히 설명할 수 있는 것이다.

주의할 점이 있는데 인터넷 스토리지는 과거 웹하드, 웹 스토리지, 파일 호스팅, 온라인 스토리지 서비스 등으로 불렸고 현재는 클라우드 스토리지 서비스라는 용어를 사용한다. 이러한 미묘한 차이로 인해 범주를 정할 때 신중하게 결정해야 한다.

또한 지나치게 신조어를 만들거나 어려운 용어를 쓰면 독자의 범주에 들지 못한다. 그렇다면 사용자가 익숙한 범주는 뭘까? 그것은 경쟁사에 있다. 여러 경쟁사가 사용하는 보편적인 서비스 범주를 벤치마킹하면 독자의 범주에 들 것이다. 반대로 새로운 범주여도 데이콤의 웹하드처럼 유행시키면 되긴 한다.

ABC는 클라우드펀딩 서비스입니다.
ABC는 클라우드펀딩 서비스의 일종입니다.
ABC는 일종의 클라우드 펀딩서비스입니다.

~한 서비스입니다.처럼 수식을 한정해서 사용하면 차이를 돋보이게 할 수 있다.

경쟁사보다 전반적으로 발전한 서비스라면
ABC는 보다 발전된 클라우드펀딩 서비스입니다.
ABC는 클라우드펀딩 2.0 서비스입니다.

특정 사용자를 위한 서비스라면
ABC는 개발자를 위한 클라우드펀딩 서비스입니다.
ABC는 주부만을 위한 클라우드펀딩 서비스입니다.

개발사가 유명하거나 공공성을 강조하고 싶다면
ABC는 NAVER가 개발하고 운영하는 클라우드펀딩 서비스입니다.

새로운 범주를 만들고 싶다면
ABC는 클라우드옥션 서비스입니다.

이렇게 범주를 작성하는 법에는 여러 가지가 있다. 범주를 신중하게 결정해야 하는 이유는 독자가 쉽게 이해해야 하는 것도 있지만 해당 서비스의 정체성, 검색어와도 연관이 있기 때문이다.

1.3 용도를 범주의 핵심 기능으로 기술하자

첫 문단이 범주가 사용된다면 두 번째 문장은 독자 관점의 용도를 적는다.

용도는 독자가 이 서비스를 사용하는 이유다. 그렇기에 서비스의 핵심 기능을 서술해야 한다.

Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.

이렇게 서비스의 핵심 기능은 서비스가 속한 범주의 핵심 기능과 같다.

1.4 특징을 장점과 강점에서 뽑아 쓰자

범주와 용도는 보편적인 내용을 적는 데에 반해 특징은 차별화하는 내용을 적어야 한다. 여기서 차별화는 서비스의 장점과 강점이다.

장점은 자기 서비스에서 잘하는 것이며 강점은 경쟁 서비스와 비교한 것이다.

여기서 장점과 강점이 헷갈릴 수 있다.

구분	국어	영어
철수	95	80
학년 평균	95	60

여기서 출수의 장점과 강점은 뭘까?

• 장점 : 국어를 잘한다.
• 강점 : 영어를 잘한다.

이처럼 장점은 자기 기준이며 강점은 주변 경쟁자와 비교한 것이다.

아무튼 서비스 개념에서 특징을 쓸 때는 장점이자 강점인 것을 쓰는 게 좋으며 장점이자 강점인 것이 없다면 합쳐서 한 문장으로 쓰는 것도 좋다.

장점과 강점을 합친 문장

ABC서비스는 최고의 안정성을 제공합니다.

장점과 강점을 나열

ABC 서비스는 간단하고 직관적인 웹 인터페이스와 안정적인 서비스를 제공합니다.

2. 정확히 이해하도록 그림과 글로 묘사하자

2.1 글에 묘사를 더하면 이해가 빠르다

묘사는 어떤 대상이나 사물, 현상을 언어로 서술하거나 그림으로 표현한다. 하지만 언어로만 서술하면 작가와 독자가 어느 정도 같은 경험을 가져야 묘사가 된다.

개발문서는 사용자와 개발자가 같은 경험을 갖고 있지 않기 때문에 그림으로 묘사하는 경우도 있다.

사용자와 개발자 국한되지 않고 개발자 끼리도 복잡한 로직은 그림으로 묘사하는 게 좋을 것이다.

물론 사내에서 같은 경험을 공유한 사람들과는 언어로 서술하거나 그림 한두 장으로 묘사가 될 수 있다.

2.2 글과 그림의 내용을 일치시키자

글과 그림의 내용을 일치시켜서 독자가 이해하기 쉽게 해야 한다.

만약 일치하지 않으면 독자는 헷갈린다. 그렇기에 그림을 넣는다면 글과 내용을 일치시켜야 한다.

2.3 객관적 묘사와 주관적 묘사 둘 다 하자

길 알려주는 주관적 묘사, 객관적 묘사

• 주관적 묘사 : 저기 앞에 큰 사거리에서 오른쪽으로 돌아서 5분쯤 가면 기차역이 보여요
• 객관적 묘사 : 두 번째 사거리에서 10시 방향으로 돌아서 300미터 가면 우측에 기차역이 있어요

이는 기획자, 디자이너, 개발자 사이에서 일하면서 생기기도 한다.

기획자와 디자이너는 주관적 묘사가 익숙하고 개발자는 객관적 묘사가 익숙하다.

개발자가 주관적 묘사를 객관적 묘사를 바꾸고 개발하고 또 디자이너와 소통할 때 주관적 묘사로 바꿔서 소통하면 개발자에게 큰 도움이 된다.

3. 논증으로 유용한 정보를 제공하자

3.1 의견을 쓰려면 근거를 대자

논증은 옳고 그름을 이유나 근거를 들어서 밝히는 것이다.

이 인스턴스의 세부 설정에 대한 글의 일부를 보자

옵션 값이 높을수록 품질이 좋아지지만 인코딩에 더 많은 시간이 소요됩니다.

default 값은 10이며, 30가량의 값을 사용해도 괜찮습니다.

첫 문장에 품질을 높이면 인코딩에 시간이 더 쓰인다는 것은 통념적이라 근거가 없어도 이해할 수 있다.

문제는 두 번째 문장에 있다. 왜 default 값은 10이며 30가량의 값을 왜 사용해도 되는지 20과 40은 안되는지 근거를 대줘야 한다.

이는 무작정 엄마가 아이에게 초코를 먹지 말라는 것과 같다.

근거를 대기에 가장 좋은 방법은 개발자가 직접 체험해서 결과를 보여주는 것이다.

default 값은 10이며, 30까지를 권합니다.

테스트 결과 30까지는 인코딩 시간이 10~20%로 소폭 늘었으며.. ~~

3.2 거칠게도 공손하게도 쓰지 말자

개발문서를 쓸 때 은근 대장 노릇을 할 때가 있다. 자기도 모르게 권력과 힘을 드러내거나 자랑한다. 대표적으로~할 수 있지만 ~하기 어렵다 가 있다.

이는 독자가 그래서 어쩌라고 말하게 된다.

또한 개발문서에는 공손한 표현은 좋지 않다. 공손하게 말하는 순간 독자가 오해할 소지가 있다.

• ~해야 합니다만 반드시 해야 하는 것은 아닙니다.
• ~하지 마십시오. 물론 큰 문제는 없습니다.
• ~할 것을 추천합니다. 혹시 더 좋은 방법이 있을 수도 있습니다.

이런 표현을 다음과 같이 바꾸자

• ~하십시오.
• ~하지마십시오.

세상 어떤 일이든 100% 확신할 수 없는데 개발문서는 독자가 느끼기에 그 %가 부풀려지기 때문에 독자에게 여지를 줘서는 안 된다.

개발자가 시킨 대로 하지 않고 우물쭈물하거나 엉뚱한 행동을 하기에 너무 공손하면 안 된다.

3.3 주장과 이유의 거리를 좁혀서 쓰자

주장을 했으면 이유를 바로 말해야 한다. 특히 개발문서는 잡지와 같이 처음부터 읽지 않고 그때그때 필요한 부분을 읽는다. 그렇기에 주장을 말했으면 중복된 이유라도 계속 붙여서 써줘야 한다.

그 방법에는 2가지가 있다.

• 주장 다음에 항상 이유를 다시 쓴다
• 주장 다음에 이유가 있는 문서로 이동할 수 있게 링크를 단다.

3.4 문제와 답의 거리를 좁혀서 쓰자

우리는 문제가 있으면 바로 답을 알기를 원한다. FAQ와 같이 문제를 검색했을 때 바로 답이 나와야 좋다. 개발 문서도 이와 같다.

구독자 목록과 관련한 groupid는 아래 방법으로 확인할 수 있습니다.

• 주소록 목록에서 주소록 이름을 클릭하여 주소록 대시보드로 이동
• 그룹을 클릭하여 그룹 목록으로 이동
• ….

답을 찾아가는 과정이 길며 이미 답을 알고 있는 독자에게는 매우 효율적이지 않다.

구독자 목록 페이지로 이동하는 방법을 모르면 다음과 같이 하십시오.

와 같이 효율적이게 읽을 수 있게 하는 게 좋다.

4. 서사를 활용해 목차를 만들자

4.1 개발과 서사

서사는 있는 사실을 그대로 순서대로 적는 것을 말한다.

누가 어떤 행동을 했고 그 행동으로 어떤 일이 일어났는지 그대로 쓰는 것이다.

개발에서도 이 서사를 지시 형태로 쓴다. 소설과 달리 스크린샷을 보여주면서 순서대로 쓸 때가 많다. 그러므로 글만 있는 소설이 아니라 글과 사진이 붙어 있는 잡지처럼 써야 한다.

푸시 서비스 설정
1. 사이드바 메뉴에서 설정을 크릭하여 확장 메뉴를 펼칩니다.
2. 푸시를 선택하여 푸시 설정 화면으로 이동합니다.
3. 푸시 섹션에서 푸시 사용 버튼을 On으로 켭니다.
…
이미지 (이미지에 1, 2, 3 표시가 있음)

보통 위 예문의 글을 본 적이 많을 것이다. 이 방식은 독자가 글과 스크린샷을 오가며 봐야 하기에 피로하고 집중하기가 어려울 것이다.

이 내용을 한 문장으로 요약하고 단어 앞에 번호를 붙여보자.

푸시 서비스 설정
푸시 서비스를 설정하려면 1) 설정 > 2) 푸시화면에서 3) 푸시 사용을 켜고..
이미지 (이미지에 1, 2, 3 표시가 있음)

4.2 독자의 수준 대신 기술의 범용성을 기준으로 쓰자

독자의 수준을 초등학생 수준이라고 생각해 보자.

스마트폰을 키고 앱스토어에 들어가면서 검색과 설치 버튼 누르는 방법을 하나하나 설명해야 한다.

그렇다고 대학교수 수준으로 쓰면 서사가 너무 짧아서 맥락이 끊긴다. 그렇기에 개발문서는 독자의 수준에 맞춰 쓰기가 까다롭다.

해결책은 기술의 범용성을 기준으로 쓰면 된다. 현재는 스마트폰을 사용해 앱을 설치하는 방법을 모르는 사람이 없다. 이러한 범용성을 기준으로 작성한다면 개발자도 독자도 좋을 것이다.

또 다른 방법으로 개발문서를 읽기 전에 기본적인 수준을 맞춰놓는 것이다. 시작하기 전에 개요를 통해 최소 분량으로 기본 지식을 설명하는 것처럼 말이다. 앱 최초 설치 후 사용법을 띄어주는 것과 비슷하다.

4.3 순서에서 단계를, 단계에서 목차를 만들자

무작정 순서를 나열하는 것보다 단계를 만들고. 해당 단계에서 목차를 만들면 좋다.

단계

순서를 나열한 것에 대해 1단계 버그 재현, 2단계 실행 코드 검색 및 일시중지.. 처럼 단계로 분리한다.

목차

이렇게 단계를 만들었으면 목차를 쓸 수 있다. 이는 하이퍼 링크의 역할도 하며 독자가 원하는 목차를 바로바로 볼 수 있게 한다.

5. 5장을 읽으며 느낀 점

• 서비스를 소개할 때 범주는 첫인상과 같다고 느꼈다.
• 서비스를 소개할 때는 무작정 개발 관련 용어로 소개하기 보다 사용자에게 익숙한 용어로 소개하자.
• 내 서비스의 범주를 잘 모를 때는 경쟁사의 범주를 참고해 보자.
• 내 서비스의 장점과 타사 대비 강점을 분리하는 거에 대해 알게 되었다.
• 글에 이미지를 첨부해서 묘사를 넣자. 다만 이미지와 글의 내용을 통합시키자.
• 개발 가이드에서 의견을 쓰면 항상 근거를 대자. 이는 2번 할 일을 1번으로 줄여주기도 할 것 같다.
• 개발 가이드에 너무 거칠거나 공손한 표현보다 정확한 표현을 쓰자.
• 개발 가이드는 독자에 수준에 맞추기보다는 기술 범용성에 맞춰서 글을 쓰자.