5장 ) 개발 가이드 쓰기

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

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

• 개발자는 독자가 이미 가진 범주를 사용함으로써 서비스의 개념을 간단하고 정확히 설명할 수 있다.

 

(참고)

일반적으로 웹 하드 서비스, 웹 스토리지 서비스, 파일 호스팅 서비스는 별도의 클라이언트를 설치하거나 ActiveX를 이용해 파일을 올리거나 내려받는다.

클라우드 스토리지 서비스는 HTTP 프로토콜을 이용해 파일을 올리거나 내려 받는다. 인터넷 브라우저에서 바로 사용할 수 있으므로 클라우드 스토리지 서비스만으로 웹 서비스가 가능하다.

범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야한다. 가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라하는 것이다.

범주는 서비스의 정체성을 나타낼 뿐만 아니라 검색어와도 연관이 있다.

 

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

두 번째 문장은 독자 관점의 용도를 주로 적는다. 용도는 독자가 이 서비스를 이용하는 이유다.

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

범주와 용도는 보편적인 내용을 적는다.

 

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

특징은 차별화하는 내용을 적어야 한다. 개발자에게 차별화는 서비스의 장점과 강점이다.

장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교해서 나은 것이다.

서비스 개념에서 특징을 쓸 때는 장점이자 강점인 것을 쓰는 것이 가장 좋다.

 

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

개발 문서에도 그림을 그려 넣어야할 때가 많다.

그림이나 사진이 있으면 글을 더 정확히 쓸 수 있다.

글과 그림이 같이 있으면 글과 그림이 같은 용어를 사용하는지 꼭 확인해야 한다.

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

개발자가 주관적 묘사를 객관적 묘사로 바꾸고, 그것을 다시 주관적 묘사로 바꿀 수 있으면 일하기가 한결 편하다.

 

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

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

개발자가 직접 체험한 결과를 알려주며 설명하는 것이 훨씬 '논증적'이다.

개발 문서에서 공손한 표현은 좋지 않다.

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

두가지 표현으로 바꾸어 사용하는 것이 좋다.

개발 문서는 독자에게 여지를 줘서는 안된다.

개발 문서는 처음부터 순서대로 읽지 않기 때문에, 주장과 이유의 거리를 좁혀서 써야한다.

비슷하게, 문제와 답의 거리를 좁혀서 써야한다.

 

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

개발에서는 어떠한 일을 하라고 지시하는 서사를 많이 쓴다.

기술의 범용성을 기준으로 하여 문서를 작성해야한다.

또는 개발 문서를 읽기 전에 기본적인 수준을 맞춰 놓는 것이 좋다.