문장과 단락을 구조화하는 법

서술식, 개조식, 도식

서술식

• '~다.'로 끝나는 완전한 문장으로 구성된 글을 말한다.
• 개발 가이드 문서를 보통 서술식으로 작성한다.

개조식

• 종결 어미(예: ~다) 대신 명사(예: 완료, 증대 등)나 용언의 명사형(예: ~했음)으로 끝내는 것을 말한다.
• 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다.

도식

• 도식은 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것이다.

글쓰기 방법 별 예시

서술식

코드 리뷰는 개발 품질을 높이기 위한 중요한 과정이다. 리뷰를 통해 개발자는 자신의 코드를 객관적으로 점검할 수 있다. 또한, 팀원 간의 지식 공유와 코드 일관성 유지에도 도움이 된다. 리뷰 문화가 잘 정착된 팀은 버그 발생률이 낮고, 유지보수 효율이 높다.

개조식

• 코드 품질 향상
• 코드에 대한 객관적 점검 가능
• 팀 내 지식 공유 및 일관성 유지
• 버그 감소, 유지보수 효율 증대

대조식

목적	주요 효과	부수 효과
코드 리뷰	코드 품질 향상	버그 감소
코드 리뷰	지식 공유	팀 일관성 유지
코드 리뷰	유지보수 효율 증대	개발 문화 성숙

좋은 이름의 기준, SMART

패키지, 클래스, 모듈, 함수, 변수를 망라해 좋은 이름인지를 확인하는 5가지 기준을 SMART로 정했다.

• easy to Search: 검색하기 쉽고
• easy to Mix: 조합하기 쉽고
• easy to Agree: 수긍하기 쉽고
• easy to Remember: 기억하기 쉽고
• easy to Type: 입력하기 쉽고

검색하기 쉽게 이름 짓는 방법

요즘에는 IDE가 잘 되어있어서 필요한 클래스, 함수, 변수를 검색을 통해 찾는다. 그렇기 때문에 검색하기 쉽게 이름 짓는 것이 중요하다. 검색하기 쉽게 이름 짓는 방법은 다음과 같다.

• 고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 붙인다.
• 에러 메시지를 저장할 상수 이름을 짓는다고 하면 다음과 같이 짓는다.
  • ERROR_SERVER_TIMEOUT
  • ERROR_NO_RESULT
• 사용자를 구별할 때는 검색하기 쉽도록 user를 붙인다.
  • userPayer
  • userBuyer
• 여기서 주의할 점은 같은 접두어를 가진 함수나 변수의 개수가 너무 많으면 안 붙이는 것만 못하다는 점이다.

사용자 에러 메시지를 제대로 쓰는 법

사용자 에러에 대처하는 메시지

회원가입을 하는데 아래와 같은 문구만 뜨면 뭘 어떻게 해야 할 지 알 수 없다.

회원 가입을 진행할 수 없습니다.

오류의 내용과 오류의 원인을 함께 알려줘야 사용자가 대처할 수 있다.

휴대폰 번호를 잘못 입력하셔서 회원가입을 진행할 수 없습니다.

에러를 해결할 방법을 사용자에게 정확히 알려주면 더 좋다.

휴대폰 번호를 잘못 입력하셔서 회원가입을 진행할 수 없습니다. 휴대폰 번호 입력란에는 숫자만 입력하십시오.

에러 메시지 작성 방법

• 에러 내용: 오류로 인한 문제와 종류
• 에러의 원인: 오류를 발생시킨 직접적이고 근본적인 원인
• 에러 해결 방법: 사용자가 오류를 해결할 가장 쉽고 빠른 방법

독자 관점에서 릴리스 문서와 장애 보고서 쓰기

고객에게 유용한 정보를 쓰자

체인지 로그는 개발자가 변경한 내용을 적는 것이다. 체인지 로그를 보는 독자는 개발자가 변경한 것이 궁금한게 아니라 뭔가 새로운 것, 바뀐 것, 그래서 자기에게 좋거나 유익한 정보들을 알고 싶어 한다.

다음과 같은 체인지 로그가 있다고 해보자.

댓글에 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다.

이 체인지 로그는 개발자 관점에서 작성되었다. 이를 고객의 관점으로 바꿔서 작성해보자.

• 개발자의 문제: 화면이 멈춘 것
• 고객의 문제: 애니메이션 스티커를 댓글에 사용할 수 없는 것

• 개발자의 문제 해결: 화면이 멈추지 않게 됐다.
• 고객의 문제 해결: 애니메이션 스티커를 댓글에 사용할 수 있다.

이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다. 댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다.

이제 개발자의 문제는 짧게 줄인다.

이제 애니매이션 스티커를 정상적으로 댓글에 사용할 수 있습니다. (화면 멈춤 문제 해결)

개조식으로 바꾼다.

애니메이션 스티커를 댓글에 정상 사용 가능 (화면 멈춤 문제 해결)

릴리스 문서는 문제 해결 보고서처럼 쓰자

문제, 문제점, 해결책, 후속 계획 순으로 적자

릴리스 문서는 결국 개발자가 문제점 하나를 선택해서 해결한 결과다. 따라서 여러 문제점 중에 어떤 문제점을 선택했는지를 독자에게 정확히 알려줘야 한다.

릴리스 문서 초안 예시는 다음과 같다.

• 문제: 사용자가 급증하면 서버가 정지
• 문제점: 잘못된 시스템 설정, 프로그램 비 최적화, 잘못된 DB 설계
• 해결책: 시스템 설정 변경
• 후속 계획: 프로그램 최적화, DB 재설계

비즈니스를 이해하는 장애 보고서 쓰기

장애 보고서의 특징

1. 장애 보고서는 개발자가 원할 때 쓸 수 없다.
2. 장애의 1차 원인은 대부분 다른 원인의 결과다.
3. 장애 보고를 받는 윗사람은 대부분 개발자가 아니다.
4. 장애를 해결했다고 해서 100% 해결한 것은 아니다.

장애 보고서를 쓸 때 사용해야 하는 글쓰기 기법

1. 질문에 대답하는 신속한 글쓰기: 장애에 대한 대화를 글로 옮기는 방법. 장애에 대해서 나눈 대화를 글로 옮긴다.
2. 원인과 이유를 찾는 분석적 글쓰기: 5Whys 기법을 활용하여 문제의 원인이 되는 인과 관계를 탐색한다.
3. 상사를 고려하는 비즈니스 관점의 글쓰기: 장애로 인한 손실 금액을 측정한다.
4. 원하는 것을 얻는 정치적 글쓰기: 장애 재발생 확률을 고려하여 %로 기준을 정해 보고한다.