저자 : 김철수
개요
말 그대로 개발자가 글을 어떻게 하면 잘 쓸 수 있을지 고민하여 읽었습니다. 단순히 기술 블로그가 아닌, 장애 보고, 릴리스 노트, 변수 네이밍, 오류 메시지 등 폭넓게 개발자가 글을 마주하는 사례들을 넣어주어서 다방면으로 도움이 됐습니다. 글을 쓰거나 보고할 때 개발자 시선보다는 비지니스 시선에서 글을 쓰는 것이 중요하다는 것도 알았습니다.
문장을 구조화하는 법
색상 RGB 값을 각가 사용하기 때문에 입력 데이터는 3차원 벡터다.
-> 입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.
문장을 쉽게 쓰려면 이처럼 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다. 이때 첫 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단을 구성할 수 있다.
보통 메서드 네이밍은 명사, 동사, 형용상의 조합이다
명사 + 명사 + 명사
동사 + 명사 + 명사
형용사 + 명사 + 명사
주석이 필요한 때도 많다
checkUserName() //사용자 이름이 3글자 이하인지 체크
-> checkUserNameUnder3Characters()
-> checkUserNameUnder3Characters() //사용자 이름이 3글자 이하인지 체크
최대한 네이밍으로 표현할 수 있으면 하되, Under가 이하인지 미만인지 헷갈릴 수 있으므로 주석을 다는 것도 방법이다.
코드는 의미를, 주석은 의도를
밥 먹자는 의미를 가진 함수의 이름을 letsEatSomething()으로 지었지만 여러 가지 의미를 가질 수 있다. 따라서 아래의 왼쪽과 같이 수정할 수 있지만 일일이 의도를 함수 이름에 넣으면 코드가 지저분해지고 가독성이 떨어진다. 적절하게 주석을 사용해서 가독성 좋은 코드를 가져갈 수도 있다.
imHungrySoLetsEatSomething() -> letsEatSomething() //내가 배가 고픈 상황
youHungrySoLetsEatSomething() -> letsEatSomething() //네가 배가 고픈 상황
imBoardSoLetsEatSomething() -> letsEatSomething() //내가 심심한 상황
또한 주석도 코드처럼 관리해야 중복되거나 최신화되지 않아 헷갈리는 상황을 막을 수 있다.
사용자 에러에 대처하는 메시지
에러 내용, 에러 원인, 에러 해결 방법을 알려야 한다. 혹시 내용과 원인이 엄청 복잡하다면 해결 방법을 먼저 제시한다
3초 후에 다시 시도하십시오.
요청하신 아이템을 인계받을 상대방에게 다른 사용자가 아이템을 인계하는 중이어서 요청하신 아이템의 인계를 시간 내에 처리하지 못했습니다
-> 상대방이 다른 사용자의 아이템을 인계받는 중입니다.
문장이 매끄럽지 않은 경우에는 원인만 간단히 써도, 해결방법이 나오기 때문에 과감히 생략해도 된다.
서비스를 이해하면 에러를 예방할 수 있다
달력 날짜를 잘못 선택하면 "날짜를 잘못 선택하셨습니다. 오늘 이후 날짜를 선택하십시오" 대신에 달력 UI를 제공하고, 오늘 이후 날짜만 클릭할 수 있도록 처리한다.
이메일 주소 입력에서 사용자 실수가 많다면, 아이디와 이메일 주소를 분리해서 입력받아 오기를 최대한 줄인다.
고객에게 유용한 정보를 쓰자
체인지 로그는 개발자 관점이 아니라 고객 관점에서 써야 한다.
다음은 개발자 관점에서 쓴 체인지 로그를 고객 관점으로 수정하는 과정이다.
댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다.
-> 댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다. 이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다. / 개발자 문제 해결 + 고객 문제 해결
-> 이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다. 댓글에서 애니메이션 스티커 때문에 화면이 멈추는 문제를 해결했습니다. / 고객의 문제 해결을 앞쪽으로
-> 이제 애니메이션 스티커를 정상적으로 댓글에 사용할 수 있습니다(화면 멈출 문제 해결) / 개발자의 문제
-> 애니메이션 스티커를 댓글에 정상 사용 가능(화면 멈춤 문제 해결) / 개조식
고객의 문제 해결이 중심이 되어야 한다. 개발자의 문제 해결 내용도 간단하게 적어줄 수 있다.
오픈 소스 라이브러리 업데이트를 통해 앱 안정성을 강화했습니다.
기타 소소한 서비스 개선과 오류가 수정되었습니다.
체인지 로그는 고객 관점으로 쓰되, 개발자 관점과 적절히 섞어서 사용할 수 있다.
상사를 고려하는 비지니스 관점의 글쓰기(장애 보고서)
(개발자 관점) 장애로 인해 사용자가 1시간 동안 결제하지 못함
(비지니스 관점) 장애로 인해 OO억 원의 매출 손실이 발생함
개발자 관점은 결제 기능이 작동하지 않는 것이지만, 비지니스 관점은 기대 매출의 손실이 발생하는 것이다. 따라서 장애로 인한 손실을 계산하는 것이 곧 비지니스 관점으로 장애를 보고하는 방법이다.
원하는 것을 얻는 정치적 글쓰기
윗사람은 보통 확정적인 대답을 원한다. 딱 부러지게 그렇다 아니다는 대답을 원한다. 심지어 재발 가능성 백분율로 말해주기까지 원한다. 왜냐하면 모호한 표현은 의사결정을 내리기 어렵기 때문이다. 아랫사람이 보카시 장난으로 말을 하면 의사결정을 할 수 없다. 그래서 개발자는 좀 더 정치적으로 확정해서 말할 필요가 있다. 재발할지도 모른다면 그냥 재발 가능성을 20%라고 말하면 된다.
범주, 용도, 특징
범주는 서비스를 소개하거나 설명하는 첫 문장인만큼 정확하고 적절하게 정해야 한다.
용도는 범주의 핵심기능으로 독자가 이 서비스를 이용하는 이유다.
특징은 서비스의 장점(자기 기준), 강점(경쟁 서비스 우위)을 적는다.
네이버도 Clova 개발 가이드 문서의 시작을 다음과 같이 범주, 용도, 특징으로 썼다.
(범주) Clova는 NAVER가 개발 및 서비스하고 있는 인공지능을 플랫폼입니다.
(용도) Clova 사용자의 음성이나 이미지를 인식하고 이를 분석하여 사용자가 원하는 정보나 서비스를 제공합니다.
(특징) 3rd party 개발자는 Clova가 가진 기술을 활용하여 인공 지능 서비스를 제공하는 기기 또는 가전제품을 만들거나 보유하고 있는 콘텐츠나 서비스를 Clova를 통해 사용자에게 제공할 수 있습니다.
(범주) Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.
(용도) Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.
(특징) AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.
요구사항을 분석하지 말고 제시하라
개발자는 고객의 요구사항을 받아서 분석해서 개발하는 것이 아니라, 고객에게 요구사항을 제시해서 고객이 선택하게 만들어야 하고 그 선택에 따라 개발해야 한다.
변화하는 요구사항에 대비하라
요구사항은 반드시 변한다... 고생 끝에 목표 시스템을 만들어 작동을 시작해도 요구사항이 바뀌고 새로운 요구사항이 들어온다. 그러니 최초의 요구사항은 단지 참고사항일 뿐이다. 요구사항이 끊임없이 변화한다는 것을 이해해야 개발자가 대응할 수 있다.
가장 좋은 방법은 요구사항 정의와 구현, 고객의 검수 사이의 시간 차이를 줄이는 것이다. 첫 번째 트랙은 목표 시스템 전체에 대해 분석-설계-구현-테스트-검수 단계를 밟는 것이다. 두 번째 트랙은 기능별로 분석-설계-구현-테스트-검수 단계를 짧게 받는 것이다. 두 번째 트랙에서는 기능별로 세부 활동에 대한 정밀한 요구를 정의한다. 이 활동은 기능을 개발하기 직전에 하는데, 이것이 중요하다.
즉, 개발하기 직전에 고객과 요구사항을 다시 한번 구체적으로 점검하는 것이다. 이때 개발자는 아이디 중복을 체크할 것인지, 비밀번호를 암호화할 것인지, 휴대전화로 본인 인증을 할 것인지, 일회용 보안 로그인 기능을 넣을 것인지 하나하나 묻고 체크해야 한다. 이를 그대로 문서화해서 고객의 승인을 받은 뒤에 곧바로 설계해서 개발한다.
느낀 점
단순히 변수 네이밍과 블로그 글 쓰는 법이 아닌, 제안서, 장애 보고서, 체인지 로그, 릴리즈 문서 사용법을 배울 수 있었습니다. 어떻게 글을 논리 정연하게 정리해야 하는지 알 수 있었고, 개발자 관점과 비지니스 관점을 잘 분리해서 이해할 수 있는 방식을 배웠습니다. 단순히 글뿐 아니라, 발표를 하거나, 개념을 설명할 때도 똑같이 적용될 수 있다고 생각합니다.
게다가, 요구사항은 언제나 바뀌기 때문에, 중간중간 구체적으로 먼저 요구사항을 검토하고 선택지를 제시하여, 최대한 의견을 좁히고 변경사항을 빠르게 캐치해야 함을 느꼈습니다. 실제로 일을 하다 보면, 본인들도 제대로 정리가 안 된 상태에서 요구사항을 만들어 넘기는 경우가 빈번합니다. 절대 감정적으로 나오지 않고 선택지를 만들어서 잘 줄일 수 있도록 의사소통 자세를 배웠습니다.
'회고 > IT도서' 카테고리의 다른 글
| 생각하는 인간은 기억하지 않는다 (0) | 2023.02.10 |
|---|---|
| 개발자 원칙 (0) | 2023.02.07 |
| 개발자를 위한 글쓰기 가이드 - 유영경 (1) | 2022.10.13 |
| UML 실전에서는 이것만 쓴다 (0) | 2022.09.20 |
| The Nature of Software Development (0) | 2022.09.15 |
