본문 바로가기
카테고리 없음

[IT 도서리뷰📘] 개발자의 글쓰기

by 서상혁 2021. 6. 18.

목차

 

 

 

개발자의 글쓰기

 

 

 

김철수 저 | 위키북스 | 2020년 07월 09일

 

들어가며

 

이 책은 내가 직접 사서 본 책이다. 근래 협업하는 일이 많아지면서, 계속해서 느끼는 것이 글쓰기의 중요성이었다. 코딩할 일 만큼 많은게 글로 쓰고 남들과 피드백을 주고 받는 상황이다. 무언가 내가 쓴 글에 2% 아쉬움을 느끼고 있는 상황이었는데 마침 베스트셀러 중 이 책이 있어서 바로 구입하게 되었다!

 

이전에 '함께 자라기' 서평에서도 얘기했듯이, 막연하게 하던 대로 한다면, 성장 속도는 매우 더딜 수 밖에 없다. 글쓰기도 마찬가지이다. 그냥저냥 평소 쓰던 대로 쓴다면 그냥저냥의 전달력을 가진 개발자로 남을 것이다. 글쓰는 것도 실력이 있는 만큼 훈련이 필요하다. 내 글의 설득력, 전달력을 좀 더 늘리고 싶고 효율적인 글쓰기를 하고 싶은 마음으로 이 책을 펴게 되었다.

 

 

글쓰기의 중요성

 

사실 나처럼 전형적인 개발자의 성격이나 특성을 가지고 있는 사람들은 대부분 글쓰는 것 자체에 대해 크게 흥미를 느끼진 못할 것이라 생각한다. 그도 그럴 것이, 컴퓨터 언어라는 것도 최대한 사람의 글의 길이를 줄여서, 효율적으로 컴퓨터가 읽을 수 있게 만든 언어이기도 하니까. 하지만 개발자에게 코딩만큼, 어쩌면 코딩 이상으로 중요한 것이 글쓰기이다.

최근 개발자의 역량 중 제일 중요하다고 평가받는 것이 바로 '커뮤니케이션' 이다. 그리고 글쓰기는 요즘같은 언택트 근무 시대에 가장 큰 커뮤니케이션 수단이다. 뿐만 아니라 이제는 라이브러리가 코딩해주는 시대이다. 조만간 AI가 코딩 상당수를 대체할 것이라 생각하고, 이미 일부분 그렇게 되고 있다. 아직 AI 가 본인의 생각을 표현하고 글 쓰는 단계까지 가기에는 무리라고 보인다. 결국 AI에 대체되지 않는 개발자가 되는 데에 큰 key는 글쓰기라고 생각한다.

 

후기

 

 

생각보다 내용이 어렵지 않고 보편적인 내용이 많았다. 다시 말하자면 쉽고 수월하게 잘 읽힌다는 뜻이다. 역시 글쓰기를 알려주시는 분의 글이라 그런지 다른 책보다 막힘없이 쭉쭉 읽혀지는 기분이 들었다. 그 분의 생각을 내 머릿속으로 골프치듯이 쑥쑥 넣어주는 기분이다. 무언가 공부는 하고 싶은데 너무 막연한 상황이라 무엇을 공부해야 될지 모르겠을 때, 혹은 출퇴근길 대중교통과 같은 곳에서 읽기 딱 좋은 책인 것 같다

 

저자분께서도 몇번 강조했던 내용에도, 결국 해당 집단이나 그룹의 협의, 혹은 상황에 맞는 글쓰기가 중요하다고 하신 것처럼, 결국 100% 정답인 글쓰기는 없다고 생각한다. SI 제안서는 현재 내 상황과는 거리가 살짝 있었고, 기술 블로그 부분은 솔직히 크게 와닿는 부분은 없었다. 전부 다 받아들이고 그 방식 그대로 외우는 것이 아니라, 이러한 방식으로 글을 쓰면 주로 좋구나 하는 식으로 받아들일 부분만 참고하기로 했다.

 

 

주요 내용들

 

개발자의 글 표현 방식

  1. 서술식
    •   '~다' 로 끝나는 완전한 문장으로 구성된 글
    •   줄거리가 있는 설명이나 이야기
    • 개발 가이드 문서
    • 예시 :
      • 이것이 서술식 설명의 예시입니다. 일반적으로 쓰는 글들의 형식이라고 볼 수 있습니다.
  1. 개조식
    • '~음' 이나 명사로 끝나는 글
    • 어떤 사항을 나열할 때
    • 여러가지 종류의 항목과 내용이 반복
    • 서술식에서 강조가 필요한 내용
    • 예시 :
      • 지금 쓰는 방식이 서술식
      • 글머리 기호를 이용
  1. 도식
    • 표나 막대, 등 그림으로 표현
    • 사물의 구조나 관계, 상태를 나타낼 때
    • 예시 : 
    • 개발자의 글 표현 방식
      이름 문장 형식
      서술식 ~다, .
      개조식 ~음, 명사, ~것
      도식 표, 막대, 그림

 

주석

  1. 되도록 주석이 필요 없게끔 하되, 주석을 안붙임으로 인해 코드가 더러워진다면 주석을 붙이는 쪽이 낫다.
  1. 검색해서 예제를 보고 따라하는 경우가 존재한다.
    • 이런 독자를 위해서는 같은 주석이라고 해도 반복해서 쓰는게 좋다.
    • 반드시 반복되는 주석을 지워야만 좋은 것은 아니다.
  1. 잘못 쓴 주석은 잘못 쓴 코드보다 리스크가 훨씬 크다.
    • 주석 리뷰의 필요성

변수 이름 정하기

  1. 변수 이름 선택, 외래어 발음 선택등에 있어서는 결국 그룹의 개연적인 합의와 컨벤션 규칙이 우선이다. (정해진 답은 없다는 뜻)
    • 약어는 보편성을 기준으로
      • VIPDM (X) / VeryImportantPersonDataManager (X) / VIPDataManager (O)
  1. '검색 잘되는 이름' 을 생각하면서 정한다.
    • 한 단계 상위 범주의 이름을 태그처럼 붙이는 방법
      • ERROR_SERVER_TIMEOUT
      • ERROR_BAD_REQUEST
  1. 중요한 단어를 앞에 붙이는 방법
    • totalVisitor (X) visitorTotal (O)
    • 검색할 때는 visitor 로 검색하게 되기 때문

중요한 5요소는 다음과 같다.

  • 검색하기 쉬움
  • 조합하기 쉬움
  • 수긍하기 쉬움
  • 기억하기 쉬움
    • 시청각적인 변수 : S3
    • 감각적인 단어 : TRQWYE < QWERTY
  • 입력하기 쉬움

 

 

체인지 로그 작성

 

체인지 로그는 너무 길면 보기 불편하고, 너무 짧으면 상사나 고객 입장에서 보기 좋지 않다. 이 두 가지의 밸런스를 잘 맞춰야 한다. 우선은 최대한 많이 쓰고, 일정한 기준으로 선정 및 분류해서 요약하는 과정을 거치는 것이 좋다.

 

  1. 선정하기
    • 독자가 관심있는 것이 최우선, 개발자가 노력을 들인것이 차우선
      • 독자 관심 X, 개발자 노력 X 는 과감하게 삭제
  1. 분류하기
    • 비슷한 체인지 로그끼리 묶음
    • 묶은 로그들의 소제목을 붙여 계층화
  1. 요약하기
    • 불필요한 부사나 조사, 어미, 형용사들을 없애고 정확한 단어로 대체
    • 예시 : '미리보기에서 간혹 리부팅되는 문제를 해결했습니다' → '미리보기 리부팅 문제 해결'
  1. 종합
    • 릴리스 내용 전체를 종합해서 한문장으로 요약
    • 첫 줄에 서술

 

릴리스 문서 작성

 

릴리스 문서는 문제해결 보고서 처럼 작성한다.

 

  1. 문제 → 문제점 → 해결책 → 후속 계획 의 과정을 따르는게 좋다.
    • 문제와 문제점의 차이?
      • 문제 : ~서비스에 사용자가 급증하면 ~서버가 정지하는 문제
      • 문제점 : DB 설계가 잘못됨 / 최적화 미스
  1. 면책 조항을 포함하는 것이 좋다.
    • 개발자의 법적 책임을 줄여줌
    • 행동이 필수인지, 권장인지, 선택인지 명확히 표시

 

장애 보고서 작성

 

장애보고서의 큰 특성은 다음과 같다.

 

  1. 갑작스럽게 쓰는 상황이 많기에 신속한 글쓰기가 필요하다.
  1. 원인의 원인을 계속 찾아나가야 한다.
    • 장애의 1차 원인은 대부분 다른 원인의 결과
    • 5 why 방법
  1. 비즈니스 관점의 글쓰기가 필요하다.
    • 독자는 보통 임원 혹은 기획, 경영자
    • 어려워도 손실을 직접 계산해보기
  1. 정치적인 글쓰기가 필요하다.
    • 100% 해결은 없음, 확정적인 대답을 결정
    • 모호한 표현 지양 (정확한 단어와 문장으로 사실표현)

 

장애 내용 → 장애 영향 → 장애 원인 → 조치 상황 → 조치 결과 → 핵심 원인 → 향후 대책

 

서비스 소개 or 메뉴얼 작성

 

작성 과정

 

시작은 범주, 용도, 특징 순으로 쓴다.

 

(범주) Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스 입니다. (용도) Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다. (특징) AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.

 

범주

  • 신중하고 정확한 표현이 필요
  • 특별한 용어보다는 누구든 이해할 수 있는 통용가능한 용어 사용
  • 차이가 돋보이는 형용사를 붙여도 좋음

 

용도

  • 독자 관점에서 작성
  • 핵심 기능을 표현 (비교적 보편적인 부분)

 

특징

  • 차별화하는 내용
  • 장점 보다는 강점이 중요!
    • 장점 + 강점이 베스트

 

그림을 제시하기

 

서비스를 표현할 수 있는 구성도 혹은 그림 제시함으로서 독자의 이해를 한층 더 슆게 할 수 있다.

 

  • 글과 그림을 일치시킬 것
    • 같은 용어를 사용하는지 확인
  • 객관적 묘사 + 주관적 묘사
    • 객관적인 요구사항 정의서
    • 주관적인 '자주하는 질문' 혹은 '도움말' 등등

 

논증의 기법

 

근거가 없어보이게 작성하면 안된다. 논증을 통해, 설득력 있는 글을 쓰도록 노력해야한다. 즉, 의견을 말했으면 통상적으로 이해가 되는 말이든지, 근거를 말하든지 둘 중 하나는 해야한다.

 

  • 주관적인 표현보다는 객관적인 근거
  • 거칠지도, 공손하지도 않은 어투
  • 주장이 들어간다면, 바로 이유를 이어서 서술
    • 자세한 내용은, 하고 링크를 거는 것도 좋음

 

답을 찾아가는 지루한 과정을 먼저 보여주기 보다는, 정답을 바로 서술하고, 그 다음 모르는 독자를 위해 과정을 서술한다.

 

예시

🚫
구독자 목록과 관련한 groupid는 아래 방법으로 확인 가능합니다. - 과정 1 - 과정 2 - 과정 3 - 과정 4

 

⭐
구독자 목록과 관련한 groupid를 확인하려면 '구독자 목록' 페이지 URL에서 'subscribed' 뒤의 숫자를 보십시오. * 구독자 목록 페이지로 이동하는 방법을 모르면 다음과 같이 하십시오. - 과정1 - 과정2 - 과정3

 

 

서사를 활용해 목차를 만들자. 순서 글머리 기호도 유용하다.

  • 한 문장으로 요약 및 단어 앞에 번호 붙이기
  • 스크린샷(그림 혹은 구성도) 의 번호와 글의 번호를 일치시키기
  • 서사가 너무 길어진다면?
    • 단계 개념을 도입 : 여러 서사를 큰 단계로 묶어서 계층형태로 표현

 

기타

 

  1. 글에도 위계와 계층이 필요하다.
    • 결국 트리형 구조가 좋은듯
    • 글머리 기호를 잘 사용해야됨
  1. 웬만하면 두괄식이 좋다
    • 선 주제 후 이유
  1. 띄어쓰기 원칙
    • "조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다."
  1. 반댓말의 선택의 중요성
    • show & invisible (X) / show & hide (O)
  1. 깨진 링크 찾기
    • 브로큰 링크 체크 닷컴
    • 구글 서치콘솔
  1. Semantic Versioning
    • X.Y.Z
    • 최초 공개 API 는 1.0.0
    • 최초의 내부 개발 버전은 0.1.0
  1. 고려사항
    • 글의 독자가 다양하다면, 독자의 수준이나 상황보다는 기술의 범용성을 기준으로 작성하자
      • 애매할 때?
        • 기본적인 필수 지식이나 수준을 '개요' 혹은 '시작하기 전에' 에 기재

 

 

728x90

댓글

티스토리툴바