의견을 쓰려면 근거를 대자#
•
논증은 옳고 그름을 이유나 근거를 들어서 밝히는 것
•
논증은 객관적이고 논리적인 방식으로 어떤 사실을 증명해서 상대를 설득하는 일
•
개발자가 의견만 말하고 근거를 말하지 않으면 독자가 납득하기가 어렵다.
•
가장 좋은 방법은 개발자가 직접 체험한 결과를 알려주는 것
// 좋은 예시
default 값은 10이며, 30까지를 권합니다. (테스트 결과, 30까지는 인코딩 시간이 10~20%로 소폭 늘었습니다. 35%일 때는 100%, 40%일 때는 200%로 인코딩 시간이 급증했습니다.)
JavaScript
복사
거칠게도 공손하게도 쓰지 말자#
•
개발자는 거칠게 가이드 문서를 쓰면 좋지 않다.
◦
좋은 예시 : ~할 수 있지만 안 쓰는 것이 낫다, ~하면 된다
•
마찬가지로 너무 공손한 표현도 좋지 않다.
◦
좋은 예시 : ~하십시오, ~하지 마십시오
주장과 이유의 거리를 좁혀서 쓰자
•
주장을 했으면 이유를 바로 이어서 말해야 한다..
•
특히 개발 문서는 잡지와 같이 순서대로 읽지 않는데, 따라서 중복되더라도 이유를 함께 말하거나 이유를 찾을 수 있는 곳을 알려줘야 한다.
•
이유를 설명하려면 너무 길어져서 일일이 쓰기 어렵다면, 짧게라도 설명하고 이유가 있는 곳을 알려주는 방법도 있다.
[대화 ID 생성]
대화 ID는 사용자의 요청을 식별하기 위히 ... 생성하는 식별자입니다. ... CIC로 사용자 요청을 전달할 때마다 마지막 대화 ID를 갱신해야 합니다.
* 마지막 대화 ID를 기억, 갱신하지 안으면 CIC가 요청을 처리하는 동안 ... 치명적인 문제가 생깁니다. 자세한 내용은 CIC > 개요 > 간접 대화 구조에서 확인하십시오...
JavaScript
복사
문제와 답의 거리를 좁혀서 쓰자
•
개발에서 문제 하나를 해결하는 방법이 하나밖에 없는 경우는 드물며, 해결 방법이 여러 가지여서 그 중 최선을 택하는 것이 개발
•
문제 해결에서 문제가 있으면 바로 답을 알기를 원한다.
•
다음과 같이 답을 먼저 알려주고 나머지는 간단히 정리하는 것이 좋다.
// 좋은 예시
[애플리케이션 등록]
네이버 개발자 센터에서 애플리케이션을 등록하려면 Application > 애플리케이션 등록 페이지로 이동해서 지시에 따르세요. 애플리케이션 등록 시 이용약관 동의 및 휴대전화 인증이 필요합니다.
JavaScript
복사
