개발자가 글을 잘 쓴다고 판단할 수 있는 기준

1. 목적이 분명한가

좋은 개발자 글은 왜 쓰는 글인지 바로 보임

나쁜 예:
로그인 관련해서 확인한 내용 공유드립니다.

좋은 예:
로그인 실패 시 오류 메시지가 표시되지 않는 문제가 있어 원인과 수정 방향을 공유드립니다.

 

 

 

 

 

2. 독자가 바로 이해할 수 있는가

개발자가 잘 쓴다는 것은 자기 머릿속에 있는 내용을 남도 이해할 수 있게 꺼내는 능력

작성자는 프로젝트 맥락을 알고 있으나 독자는 모를 수 있다

그래서 좋은 글은 필요한 배경을 적당히 제공한다

어떤 기능인가
어떤 화면인가
어떤 버전인가
어떤 조건에서 발생했는가
어떤 결과가 나왔는가
무엇을 확인해야 하는가

 

 

 

 

 

3. 사실과 의견을 구분하는가

개발자의 글은 정확해야한다

특히 버그 리포트, 장애 보고, 코드 리뷰, 기술 선택 문서에는 사실과 의견을 구분해야한다

사실:
Android 빌드에서 로그인 실패 시 오류 팝업이 표시되지 않습니다.

의견:
현재 UX상 사용자가 실패 원인을 알기 어렵습니다.

추측:
클라이언트에서 실패 응답을 UI로 연결하지 않은 가능성이 있습니다.

 

 

 

 

 

4. 애매한 표현을 구체적인 정보로 바꾸는가

개발자의 글에서 가장 흔한 문제는 애매한 표현

나쁜 예:
게임이 느립니다.

좋은 예:
보스전에서 탄환이 500개 이상 생성되면 FPS가 60에서 32로 떨어집니다.

나쁜 예:
거의 완료했습니다.

좋은 예:
기본 이동과 공격 기능은 완료했고, 피격 처리와 사운드 연결이 남아 있습니다.

 

 

 

 

 

5. 읽은 사람이 바로 행동할 수 있는가

개발자의 글은 대부분 행동으로 이어져야 한다

버그 리포트를 읽은 사람이 재현할 수 있어야 하고 

작업 보고를 읽은 사람은 현재 상태를 판단할 수 있어야 한다

README를 읽은 사람은 프로젝트를 실행할 수 있어야 한다

코드 리뷰 코멘트를 읽은 사람은 무엇을 고쳐야하는지 알아야 한다

나쁜 예:
확인 부탁드립니다.

좋은 예:
Android 빌드에서 잘못된 비밀번호 입력 시 오류 팝업이 표시되는지 확인 부탁드립니다.

 

 

 

 

 

6. 구조가 정리되어 있는가

문장이 좋아도 구조가 없으면 읽기 어렵다

 

- 버그 리포트에 좋은 구조

제목
요약
발생 환경
재현 순서
기대 결과
실제 결과
로그
첨부 자료
추정 원인

- 기술 선택 문서에 좋은 구조

문제 상황
선택지
비교 기준
장점과 단점
최종 선택
선택 이유
위험 요소
후속 작업

 

 

 

 

 

7. 제목만 봐도 핵심이 보이는가

제목은 글의 입구

나쁜 예:
로그인 문제

좋은 예:
Android 빌드에서 로그인 실패 시 오류 팝업이 표시되지 않음

나쁜 예:
성능 개선 보고

좋은 예:
오브젝트 풀링 적용 후 보스전 FPS가 32에서 58로 개선됨

 

 

 

 

 

8. 기술적 정확성이 있는가

개발자의 글은 문장이 자연스러워도 기술 정보가 틀리면 좋은 글이 아님

특히 정확해야하는 것들은 아래와 같음

엔진 버전
라이브러리 버전
API 이름
파일 경로
클래스 이름
메서드 이름
설정 위치
명령어
오류 메시지
수치
테스트 결과

 

 

 

 

 

9. 필요한 만큼만 친절한가

좋은 글은 불친절하지 않지만, 불필요하게 장황하지도 않다

초급자를 위한 글이면 배경 설명이 필요하고,

팀 내부 작업 보고라면 핵심 상태가 중요하고,

기술 블로그라면 문제 해결 과정이 필요하다

API 문서라면 예외 상황과 응답 형식이 중요하다

 

즉, 좋은 글은 독자의 수준과 상황에 맞게 설명량을 조절한다

 

 

 

 

 

10. 협업을 덜 꼬이게 만드는가

이것이 최종 기준

"이 글이 협업을 더 쉽게 만드는가?"

좋은 개발자 글은 질문과 오해를 줄이고 재현 시간을 줄인다

그리고 수정 방향을 분명하게 만든다

또, 미래의 내가 봐도 이해할 수 있다

 

결국 개발자가 글을 잘쓴다는 평가는 "글이 멋있다" 보다는 "같이 일하기 편하다"에 가깝다

 

 

 

 

 

개발자 글쓰기 평가표

개발자 글쓰기 평가 기준

1. 목적
- 이 글이 왜 쓰였는지 바로 알 수 있는가?

2. 독자 이해
- 처음 읽는 사람도 핵심을 이해할 수 있는가?

3. 구체성
- 애매한 표현 대신 조건, 수치, 대상, 결과가 들어 있는가?

4. 정확성
- 버전, 경로, 코드, 로그, 수치가 정확한가?

5. 구조
- 글의 종류에 맞는 순서로 정리되어 있는가?

6. 행동 가능성
- 읽은 사람이 다음에 무엇을 해야 하는지 알 수 있는가?

7. 사실과 의견 구분
- 확인한 사실, 작성자의 판단, 추측이 구분되어 있는가?

8. 간결함
- 불필요한 문장과 반복 표현이 줄어 있는가?

9. 제목
- 제목만 보고 글의 핵심을 예상할 수 있는가?

10. 협업 효과
- 이 글이 질문, 오해, 재작업을 줄이는가?

 

 

 

 

 

한 줄 요약

문제 상황을 정확히 정리해서 다른 사람이 빠르게 이해하고 행동하게 만드는 능력

 

 

 

 

 

 

 

Reference

https://wikidocs.net/367737

Chapter 07. 개발자가 글을 잘 쓴다고 판단할 수 있는 기준