IT 개발자들을 위한 글쓰기 가이드 포스트입니다.

주석

• 주석이 필요할 때
  • 사용자 이름이 3글자 이하인지 체크하는 함수 명을 붙인다고 예를 들어보자. CheckUserNameUnder3Characters() 라고 지을경우 영어를 못하는 사용자일 경우 Under만으로는 감이 안올 수도 있다. 그리고 이름도 너무 길다.
  • 다른 개발자를 배려하는 주석을 써야한다.

    // TODO : 아직 하지 않은 일, 앞으로 할 일
    // XXX : 위험! 여기 큰문제가 있음
    // HACK : 바람직하지 않은 해결책
    

에러 메시지

• 예외처리를 할 땐 개발자용 메시지와 사용자용 메시지를 분리해야 한다

• 에러메시지

  • 보여주는 순서 : [에러 해결 방법] -> [에러 원인] -> [에러 내용]
  • 쓰기 전에 에러를 수정하라
  • 대신 예방 메시지를 쓰자
    예) 날짜 선택 GUI를 구성할 때 이전 날짜를 선택 못하게 회색으로 비활성화시키기
    카드 번호 입력시 4자리씩 입력하도록 유도

에러 메시지 대신 예방 메시지

• 닭이 먼저? 알이 먼저?
  • 재확인 방식 : 결재 요청 -> 재확인 -> 결재 처리
  • 취소 방식 : 결재 요청 -> 결재 처리 + 취소 기능
  • 혼합 방식 : 결재 요청 -> 재확인 -> 결재 처리 + 취소 기능
  • 어떤 방식을 쓸지는 서비스와 사용자에 따라 달라짐

체인지 로그 작성

• 너무 짧아도 문제 길어도 문제 -> 읽기 좋게 적절한 양으로 쓰기
  • 1단계 : 선정하기
    1순위 : 개발자 노력 多, 독자 관심 有
    2순위 : 개발자 노력 少, 독자 관심 有
    3순위 : 개발자 노력 多, 독자 관심 無
    삭제 : 개발자 노력 少, 독자 無
  • 2단계 : 분류하기
    비슷한 체인지 로그끼리 묶어야 한다.
    예) 새로운 기능 추가, 기능 개선, 오류 수정 단위로 묶기
  • 3단계 : 요약하기
    개조식 문장으로 바꾸기(불필요한 부사나 형용사, 조사나 어미를 없애고, 정확하고 적절한 단어로 대체)
    예) 미리 보기에서 간혹 리부팅되는 문제를 해결했습니다. -> 미리 보기 리부팅 문제 해결
  • 4단계 : 종합하기
    체인지 로그의 특징을 핵심만 종합해 첫 줄에 전달하기
    종합 문장의 내용이 두 가지 이상이면 줄을 나누기
    예) 게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있게 변경 ->
    • 게임방에 더 빨리 입장
    • 게임 결과 바로 확인
• 고객에게 유용한 정보를 쓰자
  • 고객의 관점에서 정보를 쓸 경우, 다음 글은 아래와 같이 변경 될 수 있다

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

    이렇게 개발자가 문제를 해결했다면 당연히 고객의 문제도 해결된다.

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

    이제 고객의 문제 해결을 앞쪽으로 옮기자.

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

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

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

    개조식으로 바꾸자.

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

문제 해결 보고서

• 문제, 원인, 해결책, 후속 계획 순으로 적자

장애 보고서

• 질문에 대답하는 신속한 글쓰기
  • 일단 무슨 말이든 내뱉고 나서 생각을 정리하고, 질문을 받으면 답하면서 다음 생각으로 이어가는 방법을 사용하자
  • 우선 장애를 다음과 같이 아주 단순한 주어, 목적어, 서술어로만 쓰자.
    “사용자가(주어) 결제를(목적어) 할 수 없다(서술어).” 이제 이 문장에 동료가 다음과 같이 질문을 한다고 생각하고, 아는 대로 말로 대답하듯 쓰자.
  • 그 후 개조식으로 간단히 정리하자
• 상사를 고려하는 비즈니스 관점의 글쓰기
  • (개발자 관점) 장애로 인해 사용자가 1시간 동안 결제하지 못함
  • (비즈니스 관점) 장애로 인해 00억 원의 매출 손실이 발생함

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

• 예
  • (범주) AWS S3는 인터넷 스토리지 서비스입니다.
  • (용도) AWS S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.
  • (특징) AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.
• 범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야 한다.
• 용도는 범주의 핵심 기능으로 기술하자
• 특징은 장점과 강점에서 뽑아 쓰자

기술블로그 잘 쓰기

• 독자 수준이 아니라 자기 수준으로 쓰자
  • 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 그러다보면 핵심 부분은 몇줄 못 쓸 경우가 많기 때문이다.
  • 단, 독자가 이해하지 못할 것으로 예상하거나 추가 정보가 필요한 용어에는 모두 링크를 걸자
  • 핵심만 쓰고 나머지는 독자가 공부할 수 있게 터놓는 것이 현명하다.

---

ref
위키북스의 개발자의 글쓰기