테스트 코드 및 메서드 주석에 대한 고민
코드를 작성하면서 테스트 코드에 어떤 테스트라는 것을 어떻게 명확하게 표현할까, 그리고 모듈 및 클래스, 메서드 주석을 달면서 어떻게 작성해야 좋은 문서가 될까? 라는 고민을 하고 작성하였지만 여전히 어렵기만 했다. 그런던 중에서 카카오 기술 블로그에서 도움이 될 만한 글을 발견하였다.
테크닐컬 라이팅의 4대 원칙
명확성
- 테크니컬 라이팅의 첫 번째 원칙은 명확성이다.
명확성이란 핵심어나 핵심 문장이 모호하게 사용되지 않고, 대상 독자가 기술 문서를 읽을 때, 내용의 모호함이나 혼란 없이 한번에 이해하도록 하는 글이다.
-
어떤 문서를 읽을 때, 독자 입장에서 이해가 가지 않아 특정 부분을 몇 번이고 다시 읽게 된다면, 이는 명확성이 떨어지는 글이다.
-
명확성이 떨어지는 이유는 대부분의 경우 대상 독자를 제대로 파악하지 못해서 발생한다.
-
“개발자라면 모두 아는 내용인데 적어야할까?” 라는 의문이 생기더라도 모두 적어야한다.
-
“개발자들이라면 다 안다"라는 생각은 굉장히 주관적일 수 있기 때문이다.
-
대학생들이나 외부의 초급 개발자들도 쉽게 따라 할 수 있을 정도의 상세한 문서여야 한다.
간결성
-
간결성이란 특정 독자가 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구나 감탄사 등을 사용하지 않고, 쉬운 단어와 간결한 문장을 사용하는 것이다.
-
문장을 길고 복잡하게 복문으로 써야 더 있어보이고, 더 많은 정보를 담게 될 것이라는 생각은 금물이다.
-
기술 문서에서는 “~는 ~입니다.” 라는 형식의 단문을 사용할 때 더욱 명확하고 가독성이 높은 글을 작성할 수 있다.
-
정확성
-
독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 제공하는 것을 말한다.
-
명확성과, 간결성이 떨어지지만 정확성이 확보된 기술문서라면, 독자들은 시간이 많이 걸린다고 해도 해당 문서를 이해할 수 있지만 반대의 경우에는 잘못된 정보를 전달하게 된다.
일관성
-
문서에 용어, 표현, 그리고 어조 등을 일관성 있게 사용하는 것이다.
-
특히 한번 언급된 단어를 다른 방식으로 언급하는 것은 독자에게 큰 혼란을 줄 수 있고, 결과적으로 문서의 신뢰도와 가독성이 저하된다.
정리
-
“짧게 써라"라고 시작하는 문장은 테크니컬 라이팅 대 원칙중 “간결성"을 “명료하게 써라"는 “명확성에 해당한다”
-
“그림처럼 써라"라는 문장은 독자가 어떤 시스템이나 기능의 아키텍처를 보다 쉽게 이해할 수 있도록 논리적으로 기술하거나 개발 시나리오나 개발 흐름 등의 시각 자료를 활용하는 것이다.
참고 문헌
>> Home