5장. 설명, 묘사, 논증, 서사로 개발 가이드 쓰기
1. 서비스 개념을 범주, 용도, 특징으로 설명하자#
범주, 용도, 특징#
- 서비스 메뉴얼이나 개발 가이드의 첫 문단은 서비스 개념을 설명하는 자리입니다.
- 개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋습니다.
범주를 정확하고 적절하게 선택하자#
- 범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야 합니다.
- 가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라 하는 것입니다.
- 마켓팅에 관심이 있거나 스타트업 대표를 겸하는 개발자라면 서비스의 범주를 신중하게 정해야 합니다.
용도를 범주의 핵심 기능으로 기술하자#
- 첫 문단의 첫 문장에 범주가 사용된다면 두번째 문장은 독자 관점의 용도를 주로 적습니다.
- 용도는 독자가 이 서비스를 이용하는 이유입니다.
- 범주의 핵심 기능을 용도로 설명함으로써 독자의 머릿속에 서비스의 정체성을 명확히 심을 수 있습니다.
특징을 장점과 강점에서 뽑아 쓰자#
- 범주와 용도에는 보편적인 내용을 적으나, 특징은 차별화하는 내용을 작성해야 합니다.
- 개발자에게 차별화는 서비스의 장점과 강점입니다.
- 장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교해서 나은 것입니다.
2. 정확히 이해하도록 그림과 글로 묘사하자#
글에 묘사를 더하면 이해가 빠르다#
- 묘사는 어떤 대상이나 사물, 현상을 언어로 서술하거나 그림을 그려서 표현하는 것입니다.
- 글 아래에 그림을 그려넣으면 더 빨리 이해할 수 있습니다.
글과 그림의 내용을 일치시키자#
- 그림이 없는 것이 이해를 못하게 하는 것은 아니나, 더 정확히 쓸 수 있습니다.
- 글이 그림과 같이 있으면 글과 그림이 같은 용어를 사용하는지 꼭 확인해야 합니다.
객관적 묘사와 주관적 묘사 둘 다 하자#
- 글은 주관적 묘사와 객관적 묘사가 많습니다.
- 기획자에게 객관적 묘사를 기대할 수 없으므로 스스로 주관적 묘사를 객관적 묘사로 바꿔야 합니다.
- 객관적 묘사와 주관적 묘사를 다 잘하게 되면, 개발의 주도권을 가지게 되고 이후 개발이 편해집니다.
3. 논증으로 유용한 정보를 제공하자#
의견을 쓰려면 근거를 대자#
- 논증은 옳고 그름을 이유나 근거를 들어서 밝히는 것입니다.
- 논증은 객관적이고 논리적인 방식으로 어떤 사실을 증명해서 상대를 설득하는 일입니다.
- 개발자가 의견만 말하고 근거를 말하지 않으면 독자가 납득하기가 어렵습니다.
- 가장 좋은 방법은 개발자가 직접 체험한 결과를 알려주는 것입니다.
거칠게도 공손하게도 쓰지 말자#
- 개발자는 거칠게 가이드 문서를 쓰면 좋지 않습니다.
- 좋은 예시 :
~할 수 있지만 안 쓰는 것이 낫다, ~하면 된다
- 좋은 예시 :
- 마찬가지로 너무 공손한 표현도 좋지 않습니다.
- 좋은 예시 :
~하십시오, ~하지 마십시오
- 좋은 예시 :
주장과 이유의 거리를 좁혀서 쓰자#
- 주장을 했으면 이유를 바로 이어서 말해야 합니다.
- 특히 개발 문서는 잡지와 같이 순서대로 읽지 않습니다. 따라서, 중복되더라도 이유를 함께 말하거나 이유를 찾을 수 있는 곳을 알려줘야 합니다.
- 이유를 설명하려면 너무 길어져서 일일이 쓰기 어렵다면, 짧게라도 설명하고 이유가 있는 곳을 알려주는 방법도 있습니다.
문제와 답의 거리를 좁혀서 쓰자#
- 개발에서 문제 하나를 해결하는 방법이 하나밖에 없는 경우는 드물며, 해결 방법이 여러 가지여서 그 중 최선을 택하는 것이 개발 과정입니다.
- 문제 해결에서 문제가 있으면 바로 답을 알기를 원합니다.
- 다음과 같이 답을 먼저 알려주고 나머지는 간단히 정리하는 것이 좋습니다.
4. 서사를 활용해 목차를 만들자#
개발과 서사#
- 서사는 사실을 있는 그대로 순서대로 적는 것을 의미합니다.
- 개발에서도 서사를 많이 쓰지만 일어난 사건을 알려주는 것이 아니라, 어떤 일을 하라고 지시하는 것입니다.
- 글과 스크린을 오가면서 쓰는 경우, 글이 많지 않다면 한문장으로 요약하고 단어 앞에 번호를 붙이는 것이 좋습니다.
ex) 푸시 서비스를 설정하려면 (1)설정 > (2) 푸시 화면에서 (3) 푸시 사용을 켜고...
독자의 수준 대신 기술의 범용성을 기준으로 쓰자#
- 서사가 순서대로 글을 쓰는 것이지만, 단순한 사건이나 상황을 시간순으로 무조건 기술하는 것은 아닙니다.
- 서사에서 의미는 작가가 부여합니다. 사건이나 상황 그 자체가 의미 있거나 없는 것이 아니라 작가가 어떤 것에 의미를 두느냐에따라 글이 달라집니다.
- 개발자는 어떤 행동에 의미를 두고 글로 쓸지 직접 결정해야 합니다.
- 개발문서에서 서사는 결국 개발자와 독자 사이의 줄다리기를 의미합니다. 개발자는 의미 없는 것을 빼고 중요한 것은 넣기를 원합니다.
- 개발자는 독자가 누구고 어떤 실력을 가졌는지 모릅니다. 따라서 좋은 방법은 기술의 범용성을 기준으로 하는 것입니다.
- 다른 방법은 개발문서를 읽기 전에 기본적인 수준을 맞춰놓는 것입니다.
순서에서 단계를, 단계에서 목차를 만들자#
- 때로는 복잡한 것을 순서대로 말하면 글이 너무 길어질수도 있고, 맥락이 맞지 않을 때도 있습니다.
- 이를 막기 위해 단계 개념을 사용합니다.