Developer's Writing
1~2장은 기본적인 Clean Code 철학을 알고 있으면 읽을 만한 내용
3장 사용자와 소통하는 에러 메시지 쓰기
Changelog
4장 독자 관저메서 릴리스 문서와 장애 보고서 쓰기
나의 경우 Core 엔진을 리팩토링 하거나 장애 보고서를 작성할 때
근본적인 Why를 찾아야만 한다. 최초 코드 작성자가 생각 없이 짰어도 결국 그 실수나 의도를 발견해내야 한다.
예제 로그인 오류 발생 시 1. 로그인 기능이 작동하지 않는 원인이 무엇인가? -> 아이디를 13글자 이상 입력하면 서버 프로그램에서 에러가 발생한다. 2. 서버에서 에러가 발생하는 원인이 무엇인가? -> 서버 프로그램에서는 아이디가 글자로 제한된다. 3. 서버 프로그램에서 아이디가 글자로 제한된 원인이 무엇인가? -> 데이터베이스에서 아이디가 12글자로 제한된다. 4. 데이터베이스에서 아이디가 12글자로 제한된 원인이 무엇인가? -> 데이터베이스 관리자가 아이디 글자 수를 16글자에서 12글자로 바꿨다. 5. 데이터베이스에서 아이디 글자 수가 12글자로 바뀐 원인이 무엇인가? -> 데이터베이스 관리자가 실수로 아이디를 12글자로 바꿨다.
하지만 이런식의 문답 보다는 원인 대신 이유를 찾아야 한다.
로그인 기능이 작동하지 않는 원인이 무엇인가?
-> 사용자가 아이디를 13글자 이상 입력했다.
사용자가 13글자 이상을 입력하는 이유가 무엇인가?
-> 프런트 개발자가 13글자 이상 입력하게 허용했다.
프런트 개발자가 13글자 이상 입력하게 허용한 이유는 무엇인가?
-> 서버 개발자가 아이디 글자 수를 16글자에서 12글자로 제한한 사실을 프런트 개발자가 몰랐다.
프런트 개발자가 그 사실을 모른 이유는 무엇인가?
-> 서버 개발자가 프런트 개발자에게 알리지 않았다.
서버 개발자가 그 사실을 프런트 개발자에게 알리지 않은 이유가 무엇인가?
-> 서버 개발자는 데이터베이스 개발자가 알려줄 것이라 생각했다.
데이터베이스 개발자가 그 사실을 프런트 개발자에게 알리지 않은 이유가 무엇인가?
-> 데이터베이스 개발자는 서버 개발자가 알려줄 것이라 생각했다.
비개발자에게 서비스 개념 설명하기
범주, 용도, 특징
개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.
ex) AWS S3
범주 : Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.
용도 : Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.
특징 : AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.
ex) Naver Clova
범주 : Clova는 Naver가 개발 및 서비스하고 있는 인공지능 플랫폼입니다.
용도 : Clova는 사용자의 음성이나 이미지를 인식하고 이를 분석하여 사용자가 원하는 서비스를 제공합니다.
특징 : 3rd party 개발자는 Clova가 가진 기술을 활용하여 인공 지능 서비를 제공하는 기기 또는 가전제품을 만들거나 보유하고 있는 콘텐츠나 서비스를 Clova를 통해 사용자에게 제공할 수 있습니다.
그림을 이용하라
단점을 약하게 표현하고, 강점을 강하게 표현하라
개발자도 개발자의 글 쓰기도 교육을 해야한다.
기본 과정
개발자가 알아야 할 글쓰기 기본
이름과 주석
에러 메시지
릴리즈 문서와 장애 보고서
개발 가이드 작성법
전문 과정
비 개발자에게 제안서 작성해보기
기술 블로그 작성하기
최종 과정
개발 팀장으로서 개발 문서 검토하기
팀원의 글쓰기 역량 강화하기
문서 엔지니어링
Reference
Last updated
