[5장] 설명, 묘사, 논증, 서사로 개발 가이드 쓰기

 

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

 

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

개발문서에는 글과 코드만 들어가지 않는다. 그림이나 사진이 많다. 이때, 그림과 예문이 일치하지 않는 경우가 많다. 따라서 글이 그림과 같이 있으면 글과 그림이 같은 용어를 사용하는지 꼭 확인해야 한다. 

 

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

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

개발 문서에는 꽤 많은 논증이 있다. 개발자가 의견만 말하고 근거를 말하지 않으면 독자가 청개구리가 된다. 가장 좋은 방법은 개발자가 직접 체험한 결과를 알려 주는 것

---

ex. default 값은 10 이며 30까지를 권합니다. (테스트 결과, 30까지는 인코딩 시간이 10%로 소폭 늘었습니다. 35일때는 200%로 인코딩 시간이 급증했습니다.)

 

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

 

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

개발문서는 처음부터 순서대로 읽지 않는다. 그때그때 필요한 부분만 찾아보기 떄문에 주장을 말했으면, 중복되더라도 이유를 함께 말하거나 이유를 찾을 수 있는 곳을 알려줘야 한다.

 

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

개발에서 문제 하나를 해결하는 방법은 여러가지 이므로 그 중 최선을 택하는 것이 개발 과정이다. 개발 문서가 사실상 문제 해결 문서이므로 문제 바로 다음에 답이 나와야 한다.(답을 찾아가는 과정을 보여줄 필요가 없음)

 

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

개발에도 서사를 많이 쓴다. 주로 프로그램의 스크린 숏이 주가 되어 순서대로 말할 떄가 많다. 이떄, 스크린 숏이 주가 되므로 그림이나 사진이 글과 붙어 있는 잡지 처럼 글을 써야 한다.

 

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

개발자는 어떤 행동에 의미를 두고 글을 쓸지 직접 결정해야 한다. 개발자가 쓴 개발 문서의 독자는 매우 다양하기에 독자의 수준에 맞춰 쓰기가 매우 어렵다. 

 

따라서 다음을 기반으로 작성하는 것이 좋다.

기술의 범용성을 기준으로 작성
개발 문서를 읽기 전, 기본 적인 수준 통일 (ex. 개요 항목에 최소 분량으로 기본적인 지식 설명...)

 

• 순서에서 단계를, 단계에서 목차를 만들기