avatar

풀스택 웹🌐 개발자 지망생 🧑🏽‍💻
➕ 인공지능 관심 🤖

Categories

Recent views

  • 1
  • 2
  • 3
  • 4
  • 5

개발자 글쓰기 정리

  1. 개발자의 글이란?
    • 문장 구조화
    • 따옴표, 영문 대문자와 표기법
    • 이름 잘 짓기
      • 주석 달기
      • 에러 메시지 체크 리스트
        • 릴리스 문서 체크 리스트
        • 장애 보고서 체크 리스트
          • 서비스 메뉴얼, 개발 가이드 체크 리스트
          • SI 제안서 체크 리스트
          • 기술 블로그

          개발자 글쓰기 정리

          ℹ️ 원문 책

          개발자의 글쓰기 (김철수 위키북스)를 읽고 정리한 내용입니다.

          개발자의 글이란?

          개발자의 글은 주석, 에러 메시지, 릴리스 문서, 개발 가이드, SI 제안서 등이 존재

          개발자 글에서 중요한 원칙 세가지

          • 정확성
          • 간결성
          • 가독성

          단, 이 셋은 서로 대치하는 경향이 있다.

          • 정확하게 글을 쓰면 간결하지 않고 가독성이 나쁨
          • 간결하게 쓰면 정확하지 않음

          ∴ 상황에 맞게 이 관계를 잘 조율하자.

          문장 구조화

          문장을 구조화하는 법

          🧾️ 예시 문장

          색상 RGB 값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터이다.

          🧾️ 구조화 과정

          1.중요 주어 앞으로

          입력 데이터는 색상 RGB 값을 각각 사용하기 때문에 3차원 벡터이다.

          2.인과 관계에 따라 문장 나누기

          입력 데이터는 색상 RGB 값을 각각 사용한다. 그래서 입력데이터는 3차원 벡터이다.

          3.중요한 문장 앞으로

          입력 데이터는 3차원 벡터이다. 입력 데이터는 색상 RGB 값을 각각 사용하기 때문이다.

          4.중복되는 주어 삭제

          입력 데이터는 3차원 벡터이다. 색상 RGB 값을 각각 사용하기 때문이다.

          서술식, 개조식, 도식 활용법

          • 서술식 : 이 문장처럼 완전한 문장형으로 ‘~다’로 끝나는 문장이다.
            주로 설명과 논증, 개발 가이드 등에 사용한다.
            줄거리나 인과 관계가 뚜렷한 경우 서술식이 유리하다
          🧾️ 서술식 예시

          4가지 푸시 알림으로, 공지 알림과 메시지 알림, 친구 등록 알림이 존재하는데, 공지 알림은 서비스 변경이나 장애, 이벤트 등 메신저 운영사가 직접 보내며, 오전 9시부터 6시 사이에만 발송합니다. 메시지 알림은 등록된 친구가 메시지를 보냈을 때 자동으로 시스템이 전송하며, 친구 등록 알림은 새로운 친구가 등록되었을 때 알려주며, 친구 해제 알림은 친구가 탈퇴 시 알려줍니다.

          • 개조식 : 명사나 명사형으로 끝나는 문장.
            주로 릴리스 문서, 장애 보고서 등에 사용
            여러 가지 종류의 항목과 내용이 반복되면 개조식 사용
          🧾️ 개조식 예시

          • 공지 알림: 서비스 변경이나 장애, 이벤트
            ※ 메신저 운영사가 오전 9시부터 오후 6시 사이에 직접 발송

          • 메시지 알림: 등록된 친구가 메시지를 보냈을 때 시스템이 자동으로 전송

          • 친구 등록 알림: 새로운 친구가 등록되었을 때

          • 친구 해제 알림: 친구가 탈퇴했을 때

          • 도식 : 항목의 관계가 명확히 규정되고 중복, 누락이 생긴다면 도식 사용
          종류 설명
          도식 표나 그림, 상태도를 이용해 표현하는 것
          서술식 이 문장처럼 완전한 문장형으로 ‘~다’로 끝나는 문장이다
          개조식 명사나 명사형으로 끝나는 문장.
          🧾️ 도식 예시
          알림 종류 상황 발송 방식 발송 시간
          공지 서비스 변경, 장애, 이벤트 수동(운영사) 9~18시
          메시지 등록된 친구 메시지 발송 자동(시스템) 제한 없음
          친구 등록 새로운 친구 등록 자동(시스템) 제한 없음
          친구 해제 친구 탈퇴 자동(시스템) 제한 없음

          개조식 서술 방식에 따른 글머리 기호

          기호를 이용해 문장의 내용, 문장 간의 관계, 순서 등을 한눈에 파악할 수 있어 중요하다.

          • 설명: 내용을 구체적으로 설명하고, 하위 요소로 나눌 때 이용, 하위 요소로 갈수록 크가 작아지고 들여쓰기가 되어야 한다.
            • ex) ■, □, ○, ●, -, *, ※ 등
          • 묘사: 내용을 그림으로 표현 시, 어떤 요소나 영역을 표시하기 위한 문자
            • ex) ⓐ, ⓑ, ⓒ, ①, ②, ③ 등
          • 논증: 내용이 논리 관계(귀납, 연역, 인과, 유추, 비교, 단계 등)로 구성 시 사용
            • ex) ∴, ∵, >,<, =, 👉 등
          • 서사: 순서나 단계를 나타낼 시, 사용,
            • ex) 1, 2, 3, 가, 나, 다 등

          단락을 구조화하는 위계

          문서에는 문단 사이의 위계가 존재한다. 위계는 위치와 계층을 합친 말이다.
          이를 통해 가독성이 늘어나고 이해하기 쉬워진다.

          • 위치: 내용의 포함 범위와 자세한 정도에 따라 결정됨
            주로 들여쓰기와 기호를 이용해 표현한다.
          • 계층: 내용의 중요도나 핵심 주제에 따라 결정됨
            주로 글씨 크기, 굵기와 모양, 밑줄 등으로 표현한다.

          위 문장은 위계를 이용하여 표현되었다.
          중요한 글씨는 굵게 표시하여 계층을 표현하였고, 들여쓰기와 기호를 통해 위치를 표현하였다.

          따옴표, 영문 대문자와 표기법

          큰따옴표와 작은따옴표

          | | 한글 따옴표 규정 | 비즈니스 문서 | 컴퓨터 공학 |
          | ———– | ———————————— | ————————————————– | ——————————— |
          | 큰 따옴표 | 화자간 직접 대화, 말이나 글 인용 | 책, 신문명, 대제목 | 문자열 표현 |
          | 작은 따옴표 | 인용구 안의 인용구, 마음속으로 한 말 | 소제목, 예술 작품명, 법률, 규정, 내용 강조 및 비교 | 문자 표현, SQL 쿼리, 자바스크립트 |

          • SQL 쿼리에서는 다른 프로그래밍 언어에서 SQL 쿼리문을 큰따옴표로 인용하는 경우가 많아 작은 따옴표를 많이 사용한다.
          • 자바스크립트는 HTML이 주로 큰 따옴표를 사용하므로 충돌을 막기 위해 작은 따옴표를 많이 사용하지만, 따옴표 처리를 위해 번갈아가며 사용하기도 한다.

          대문자를 사용하는 곳

          • 고유 명사 첫 글자 : ex) I went to Tokyo

          • 이름 앞에 오는 직함 : ex) Doctor Mr.Micheal

          • 책, 신문, 잡지, 음악, 영화 이름의 첫 단어와 마지막 단어의 첫 글자, 관사
            ex) Marvel’s The Avengers

          • 요일명, 휴일명, 역사적 사건, 월, 역사적 기간의 첫 글자 : ex) World War 2

          • 천체 이름 : ex) Mars, Jupiter

          공통적으로 중요하거나 특정한 것의 첫 글자, 명사나 관사는 소문자이다.

          표기법


          PascalCase: 중요하고 고유명사인 경우가 많으므로 주로 클래스명, 인터페이스명에 사용
          ex) interface Menu, class CoffeeMenu implements Menu

          camelCase: 주로 동사로 시작하는 경우가 많기 때문에 변수명, 메소드명에 사용
          ex) int totalCount = 0;, void orderCoffee()

          snake_case: 일부 프로그래밍 언어에서 메소드명, 변수명에 사용
          ex) def add_coffee():, int count_coffee

          SCREAMING_SNAKE_CASE: 강조 및 주의를 위해 변하지 않는 값, 상수에 사용됨
          ex) static final int COFFEE_MAX = 10;

          kebab-case: 빼기 기호(-)로 해석되는 경우가 많아 사용 안함

          nocase: 변수, 클래스 등과 구분하기 위해 주로 패키지나 모듈명에 사용
          ex) android.wikibook.developerwriting, import developerwriting

          BEM(Block, Element, Modifier) case: CSS에서 사용, 대상의 요소와 상태를 구분하여 표시할 때 사용한다.
          예시들
          - .form__button {} : button이 form 내부에 요소로써 포함되므로 __로 이어줌
          - .form__button--disabled {} : disabled는 button이 가지고 있는 특성 혹은 속성이므로 --로 이어준다.

          이름 잘 짓기

          • 의미를 알 수 있고 가독성이 높은 이름
            ex) int a, float b(X), int userCount, float userAvgRating(O)

          • 앞선 표기법 에서 설명한 네이밍 컨벤션 준수

          • 너무 길거나 짧지 않게 보통 16글자 이내, 3단어를 조합
            • 클래스명: 3.18 단어
            • 함수명: 3.36 단어
            • 변수명: 2.57 단어

          • 명사, 동사, 형용사의 조합

          • 복수형 s 대신 Array나 ListOf를 사용
            ex) checkUserNames(X), checkUserNameArray(O)

          • 약어는 조심히 접근, 통용되는 약어만 사용하자
            ex) AWS, OOP, i, j, k (O), Total Number Of Visitor -> TNOV (X)

          • 중요한 단어를 앞에 두기
            ex) int totalVisitor(X), int visitorTotal(O)
            • 검색에도 편하고, 가독성에도 좋음
          • 범주화 이용
            ex) TIMEOUT, NO_RESULT(X), ERROR_TIMEOUT, ERROR_NO_RESULT(O)
            • 검색에 편하고, 가독성에 좋음 2
          • 속성이 아닌 개념과 역할을 중점으로 이름 짓기
            ex) strong_text, h1, blue_text(X), subtitle, title, emphasis(O)
            • 속성으로 이름을 지으면 속성이 바뀌면 전부 다시 바꿔줘야 함.
          • 오타가 나기 쉬운 변수명 자제
            ex) success, lambda, Referrer, getTTTinTTTime, continuous

          주석 달기

          ℹ️ 더욱 자세한 내용은 주석 참조

          주석은 프로그래밍 언어마다 다양하게 #, //, /**/, ----, {%%} 등을 이용해 주석을 단다.

          ✍ 각 프로그래밍 언어는 보통 여러 줄을 한꺼번에 주석 처리하기 위한 방법을 지원한다.

          주석의 종류

          • 헤더 주석(Header Comment)
            • 각 파일 상단에 존재하는 주석
            • 작성자, 작성 시간, 해당 코드들의 동작들을 주로 설명한다.
          🧾️ 파이썬 헤더 주석 예시

          source here 

          #!/usr/bin/env python3 #인터프리터에게 실행 파일임을 명시하고 python3 버전임을 명시
# -*- coding: utf-8 -*- 
{: #coding-utf-8}# 파일의 인코딩을 식별
#----------------------------------------------------------------------------
# Created By  : name_of_the_creator 
{: #created-by-name-of-the-creator}
# Created Date: date/month/time ..etc
{: #created-date-date-month-time-etc}
# version ='1.0' 
{: #version-1-0}
# ---------------------------------------------------------------------------
{: #}
""" Details about the module and for what purpose it was built for""" 
# ---------------------------------------------------------------------------
{: #}
# Imports 
{: #imports}# 임포트 모듈들에 대한 설명
# ---------------------------------------------------------------------------
{: #}
from ... import ...
          🧾️ C 언어 헤더 주석 예시 
          /**
* File: compute_blackjack_odds.C
*
* Author: junseok Yun (m********@naver.com)
* Date: 2022 08 09
* 
* Description:
*     This file contains code which simulates a blackjack game.         
*
* Note:
*     All Inputs should be Integer.
*     DO NOT REMOVE COMMENTS IN HERE.
*     
*/
          • 함수나 클래스 내부 주석
            • 함수 헤더, 혹은 클래스 헤더라고 불리우며, 해당 모듈의 목적을 설명함.
            • 함수나 클래스 상단에 적기도 하나
            • 최신 프로그래밍 언어와 IDE들은 내부의 주석을 인식하여 힌트를 주기도 하므로, 내부에 적는 게 좋다.
          🧾️ 파이썬 함수 예시 
          def test(a: str, b: int):
	"""
	test function test comment.
		Args:
			a(str): a value
			b(int): b value
		Returns:
			int: result
	"""
	return a + b
          • 줄 주석(In-Line Comment)
            • 이해하기 힘든 코드 오른쪽이나 위쪽에 설명을 위해 첨가

          주석의 내용

          • 코드 메타 데이터
            • 주로 헤더 주석 혹은 내부 주석으로 작성자, 작성일, 파일명, 코드 변경 이력 등을 적음
            • IDE와 협업 소프트웨어의 발전으로 굳이 적을 필요 없어짐
          • 너무 복잡한 알고리즘
            • 복잡한 알고리즘을 설명하기 위해 각 단계를 코드로 설명
          🧾️ 조합 생성 파이썬 코드 중 일부 
          def genCombination(listOfNumbers, indexOfCombination):
.
.
    if indexOfCombination == 0: # 마지막 원소의 자리를 바꾸면
        result.append(list(combination))  # 완성된 조합을 추가
.
.
          • 코드 원리나 필요성
          // 다익스트라 알고리즘을 이용한 알고리즘
// 응답속도를 낮추기 위해 필요함
          • 새로운 발견
          // 해당 코드의 순서를 바꾸면 느려짐
// 나중에 원인 확인 바람
          • 예상 질문과 답
          // 이 변수가 필요한 이유는 개발자 가이드 3장 2절 참조 바람
          • 계획된 일, 주의, 개선 아이디어
          // - [ ] TODO: 함수 리펙토링 
// 이 코드는 서버측에서 처리하는 편이 빠르고 사용자 경험에 좋을 것 같다.
// WARN: 해당 변수를 절대 직접 참조로 구현하지 말것
          • 다른 사람에게 도움 요청
            ```
            // 사진 변경 애니메이션 인자의 경우 결정을 위해 UI/UX 담당자와 상의가 필요함
          - **개발자의 속마음 표현**

          // 이 코드 어떻게 돌아가는지 모르겠다. 일단 된다.

          ```

          주석 팁

          • 이름 을 잘 짓거나 리팩토링을 잘하면 주석을 상당히 줄일 수 있다.
          🧾️ 구린 명명, 리팩토링에 주석 사용 
          // 스크린 최대 높이를 480으로 고정
int h = 480;

// 바뀐 화면에 알맞게 로그인창 위치 변경
object loginElement = document.getElementById("login");
loginElement.x = getNewLoginPositionX(h);
loginElement.y = getNewLoginPositionY(h);
          🧾️ 좋은 명명, 리팩토링에 주석 삭제 
          int screenHeightMax = 480;

refreshLoginPositon();
          • 영어를 잘못하거나 심각한 오해, 오류의 소지가 있다면 주석 반드시 사용
          🧾️ 유저명의 최소 글자수 제한 체크 함수 
          checkUserNameUnder3Characters() // 3 글자 '이하' 인지 확인
          • 주석의 반복할 때와 생략할 때
            • 주석의 반복이 필요 없을 때 : 같은 혹은 비슷한 기능에 대한 주석이 가까운 곳에 존재
            • 주석의 반복이 필요할 때 : 같은 혹은 비슷한 기능이어도, 해당 주석이 먼 곳에 존재
              • 많은 개발자들은 필요한 부분만 읽기 때문
          • 주석의 발췌와 요약 : 주석은 짧을 수록 좋으므로, 비슷한 기능, 주석의 반복 시 인용이나 요약을 이용할 수 있다.
          🧾️ example 
          // 카카오 로그인 SDK 사용
compile group: 'com.kakao.sdk', name: 'usermgmt', version: project.KAKAO_SDK_VERSION
// push SDK 사용
compile group: 'com.kakao.sdk', name: 'push', version: project.KAKAO_SDK_VERSION
// 그외 서비스 SDK 사용
          • 주석 또한 리뷰와 디버깅의 대상으로 생각하자
            즉, 잘못 쓰거나 나쁜 주석이 있는지 언제나 살펴보자

          에러 메시지 체크 리스트

          • 에러 메시지에 포함되어야 할 것들
            • 에러 결과 ex) 사용자 가입을 진행할 수 없습니다.
            • 에러 원인 ex) 자기소개란 내 비속어 사용 불가
            • 에러 해결 방법 ex) 비속어를 제외해 주세요.
            • 에러 이후 행동 선택 ex) 자기소개란 비우기 혹은 수정을 위해 자기소개란 유지하기

            에러 내용에 따라 일부 생략하거나 제시 순서를 바꿀 수 있다. 예를 들어 에러 원인인 “비속어 발견” 대신 에러 해결 방법인 “비속어를 제외해 주세요”만 적어도 사용자는 이해할 것이며, 가독성이 늘어날 것이다.

          • 개발자용 에러 메시지와 사용자용 에러 메시지를 분리
            • 사용자 경험, 보안 상 치명적인 결과를 불러옴

          • 확인 버튼과 취소 버튼의 순서는 통일할 것
            확인 버튼과 취소 버튼의 순서는 회사나 정책마다 다르다.
            하지만 순서가 일정하지 않으면 사용자는 실수로 누를 확률이 높다.
            회사의 이익을 위해 원하는 버튼의 크기나 색감을 눈에 띄게 바꿀 수 있다.

          • 사용자 반복 에러를 막기 위해 사용 제한 횟수나 에러 횟수를 보여주기
            이를 통해 사용자는 더욱 신중하고 주의 깊게 행동을 하게 됨
            ex) 로그인 암호 통과 실패 메시지에서 로그인 기회 횟수 보여주기

          • 에러가 나지 않도록 예방하는 방법을 생각해보자.
            ex) 호텔 예약 달력 선택 기능에서 내일 이후 날짜만 고를 수 있게 하기

          릴리스 문서 체크 리스트

          릴리스 문서 순서

          1. 릴리스 문서에 적을 변경 로그 선정
          회사 선호 사용자 선호 개발자 선호 순위 수준 예시
          O O O 1 자세히 새롭고 신기하고 경쟁성 있는 새 기능(ex) 인공지능 추천)
          O O X 2 간단히 자원 추가 등의 쉬운 작업의 영향 (서버 증설로 서비스 쾌적)
          O X O 3 간단히 어려운 신기술을 이용한 기능 변경
          O X X 4 맨 아래 주석 면책 조항, 정책 변경
          X O O 5 자리가 남으면 추가 릴리즈 계획, 작업 과정
          X O X 6 통합하여 언급 자잘한 오류 수정
          X X O 삭제 삭제 전문 기술과 노력이 필요했던 피해가 없던 오류
          1. 비슷한 변경 로그끼리 분류
          🧾️ 변경 로그 예시
          • 게임 준비
            • 미리 보기에서 간혹 리부팅 되는 문제 해결
            • 빈 게임방을 자동으로 검색하는 기능 추가
            • 닉네임 만들 시 특수 문자 기능 추가
          • 게임 중
            • 고해상도 폰에서 아이콘 찌그러지는 오류 수정
            • 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
            • 애니메이션 스티커가 멈추는 오류 수정
          • 게임 종료
            • 최근 기록이 상위에 올라오도록 개선
            • 게임 종료 후 바로 순위 볼 수 있도록 개선

          위는 사용자 기준으로 분류한 것이며, 개발 관점에서 비슷한 관점으로 묶을 수도 있다.
          ex) 기능 추가, 기능 개선, 오류 수정

          1. 요약: 개조식 문장, 형용사, 조사, 어미 정확한 단어로 변경
          🧾️ 요약
          • 게임 준비
            • 미리 보기 리부팅 문제 해결
            • 빈 게임방 자동 검색 기능 추가
            • 닉네임 만들 때 특수 문자 입력 기능 추가
          • 게임 중
            • 고해상도 안드로이드/IOS 환경에서 아이콘 뭉게짐 오류 수정
            • 가로/세로 화면 전환 시 하단 메뉴 누락 수정
            • 애니메이션 스티커 오류 수정
          • 게임 종료
            • 최근 기록이 상위에 올라오도록 수정
            • 게임 종료 후 바로 순위를 볼 수 있도록 개선
            • 용량이 큰 사진 등록 시 휴대전화 메모리 사용 감소
          1. 종합: 여러 로그들의 특성과 결과를 하나로 뭉침, 분석의 반대
          🧾️ 종합

          사용자 편리성 개선

          • 게임에 더 빨리 입장
          • 게임 결과 바로 확인 및 개선

          [세부 내용]

          • 게임 준비
            • 미리 보기 리부팅 문제 해결
            • 빈 게임방 자동 검색 기능 추가
            • 닉네임 만들 때 특수 문자 입력 기능 추가
          • 게임 중
            • 고해상도 안드로이드/IOS 환경에서 아이콘 뭉게짐 오류 수정
            • 가로/세로 화면 전환 시 하단 메뉴 누락 수정
            • 애니메이션 스티커 오류 수정
          • 게임 종료
            • 최근 기록이 상위에 올라오도록 수정
            • 게임 종료 후 바로 순위를 볼 수 있도록 개선
            • 용량이 큰 사진 등록 시 휴대전화 메모리 사용 감소

          릴리스 문서 팁

          • 고객에게 유용한 정보 적기

          • 너무 어려운 기술적 내용 적지 않기

          • 추가로 미래 개발 중인 기능이나 주시하고 있는 오류 등을 적어주기

          • 자세한 내용을 적고 싶을 때: 문제, 문제 원인, 해결책, 후속 계획 순으로 적기
            ex) 서비스에 사용자가 급증하면 서버가 정지하는 문제는 시스템 재설정으로 해결했습니다. 추후 프로그램 최적화와 DB 재설계도 검토하겠습니다.

          • 유의적 버전( Semantic Versioning ) 지키기

          • 법적인 문제 고려하기(면책 조항)
            ex) 이 릴리스 노트의 내용은 예고 없이 변경될 수 있으며, 어떠한 내용도 추가 보증할 수 없고, 내용의 결과에 대해 책임을 지지 않습니다.

          장애 보고서 체크 리스트

          • 신속하고 빠르게 정리된 보고서
            • 상부에서 빠르게 보고서를 보고 재빨리 대처해야 한다.
            • 장애 내용, 장애 영향, 장애 원인, 조치 상황, 조치 결과, 핵심 원인, 향후 대책 등이 포함되어야 함
          • 원인과 이유가 존재하는 분석적 보고서
            • 단순한 1차적 원인이 아닌 근본적 원인을 보고해야 한다.
              ex) 로그인 기능이 작동하지 않은 이유는 프런트 개발자가 13 글자 이상 입력하게 허용해서 (X), 로그인 기능이 작동하지 않은 코드를 내버려둔 이유는 개발자 간의 커뮤니케이션이 문제여서(O)
          • 비 개발자를 고려한 비즈니스 관점 보고서
            • 보고 받을 경영진은 손실로 따지므로 비즈니스 적인 요소를 넣어야 한다.
              • 장애로 인한 기대 매출 손실에서 지연 매출을 뺀 매출 손실
              • 비슷한 다른 사고 사례
              • 고객들의 이미지 변화
          • 정치적, 방어적, 공격적 보고서
            • 원하는 것을 얻고, 책임을 피하고, 반복되는 장애를 피하기 위함
              ex) 유지 보수 팀의 관리 부주의가 남아있는 한 재발 가능성 높음, 서버 보안팀 구성 안하고 개인정보 유출 시 대표이사 100% 구속

          서비스 메뉴얼, 개발 가이드 체크 리스트

          범주, 용도, 특징

          • 범주, 용도, 특징이 필수적으로 들어가야 하며, 제일 먼저 설명되어야 함.
            • 범주: 서비스를 한마디로 정의하는 문장(누가 무엇을 어떻게)
              ex) Amazon S3는 아마존에서 운영하는 인터넷 스토리지 서비스입니다.
            • 용도: 서비스의 용도
              ex) Amazon S3를 이용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색 가능
            • 특징: 경쟁적이고 차별화된 부분
              ex) AWS Management Console로 간단하고 직관적인 웹 인터페이스를 통해 여러 작업 수행 가능

              범주

          • 범주 구성 시 남들이 이해할 수 있는 보편적인 단어에 추가로 강력한 마케팅을 위한 수식어를 추가
            • Amazon S3를 ‘웹 하드’ 같은 익숙한 단어를 이용하거나 ‘클라우드 스토리지’ 같은 선도적인 단어를 사용할 수 있다.
            • 경쟁사 보다 발전된 기술 (“클라우드 스토리지 2.0”), 특정 사용자 겨냥(“개발자를 위한”), 회사 자랑(“아마존에서 운영하는”) 등의 수식어를 붙여도 된다.

              용도

          • 용도는 범주의 핵심 기능, 즉 사용자 관점 용도로 기술
            용도가 많을 경우 길게 늘어뜨린 뒤, 공통점과 특성을 묶어 요약해보자.
            ex) Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장 및 검색 가능

          특징

          • 특징은 보편적이지 않고 차별화된 강점과 강력한 장점을 기술
            • 장점은 자기 기준에서 강력한 것 (ex) Amazon S3의 안정적인 서비스)
            • 강점은 경쟁사와 비교해 특별한 것 (ex) Amazon S3의 간단하고 직관적인 웹 인터페이스)
              ex) 아마존 S3는 안정적인 서비스와 간단하고 직관적인 웹 인터페이스를 제공합니다.

              기타 팁

              표현과 논술 팁

          • 주관적, 정성적 표현을 객관적, 정략적으로 표현하자.
            • 디자이너, QA, 고객과의 협의가 쉬워지고 변경할 것이 줄어든다.
              ex) ‘눈에 잘 보이는 크기의 창’ -> ‘최대 높이 765px, 너비 600px 이하의 반응형 크기의 창’
          • 의견에 대한 근거를 제시하자.
          🧾️ ❌ 잘못된 예 
          - 옵션 값이 높을수록 품질이 좋아지지만 인코딩에 더 많은 시간이 소요됩니다.
- default 값은 10이며, 30 가량의 값을 사용해도 괜찮습니다.

          품질과 인코딩 시간의 관계를 잘 모르겠고, 왜 30까지 사용해도 되는지 이유가 없음

          🧾️ ☑️ 옳은 예 
          - default 값은 10이며, 30까지는 인코딩 시간이 10~20% 정도 소폭 증가합니다.
- 인코딩 시간은 35 일때는 100% 증가, 40 일때는 200% 증가합니다.

          객관적인 근거가 잘나와있어 개발자가 판단하기 쉽다.

          • 너무 거칠게 혹은 공손하게 쓰지 않기, 확실하게 쓰기
            • 가독성을 해치고, 의미를 모호하게 만든다.
              ex) ~할 것을 추천합니다. ~를 사용하지 않으면 어려울 것입니다.(X)
              ex) ~를 사용하십시오.(O)
          • 근거가 나온 뒤에는 바로 이유가 나오기
            앞선 문장 구조화 에서 나온 내용이다.
          • 문제를 설명하면 곧바로 답을 보여주기
            가독성과 이해하기가 쉬워지며, 개발자와 사용자는 문제를 해결하기 위해 메뉴얼, 가이드를 보므로 바로 답을 보여주는 편이 좋다.
          • 사용자 메뉴얼은 쉽게, 개발자 가이드는 어렵지만 간결하게 써야 된다.
            개발자는 어차피 용어를 알아들을 것이며, 빠른 접근이 중요하다.

          서사와 그림 활용 관련 팁

          • 체계적인 그림와 구성도를 첨부하면 이해가 쉽다
            • 그림과 구성도의 원리, 용어 등을 글과 일치 시키자
          • 설치 메뉴얼, 개발 환경 설정 같이 그림과 서사가 위주인 내용은 글을 많이 요약해서 표현하자.
          🧾️ ❌ 틀린 예

          [다른 폴더 보관함 열기]

          1. 좌측 아래의 ‘다른 보관함 열기’ 버튼을 클릭합니다.
          2. ‘열기’ 버튼을 클릭합니다.
          3. 원하는 폴더를 클릭하여 엽니다.
          🧾️ ☑️ 맞은 예

          [다른 폴더 보관함 열기]
          다른 보관함을 열려면 ① 다른 보관함 열기 > ② 열기 버튼을 눌러 원하는 폴더를 엽니다.

          • 순서가 있는 서사는 너무 종류가 많을 경우 종합하여 나누자.
            릴리스 문서 4번 ‘종합’ 때처럼 나누면 된다.

          SI 제안서 체크 리스트

          솔루션 제안서는 대부분 그림과 표, 시스템 구성도 등으로 이루어져 있다.

          내용 관련 팁

          • SI 제안서에서 포함되는 내용들
            • 기술 부문 : 시스템 기능, 사양, 구성 장치 내용, 규격도…
            • 전략적 제안들 : 시스템 구축 목적, 시스템 구축 전략 , 소프트웨어 개발 방안, 테스트 방안, 향후 시스템 발전 방안, 기대 효과, 개발의 특징, 개발 방안의 장점…

          • 시스템 구성도 작성법
            제안 요청서에 존재하는 시스템 구성도를 분석해 새롭고 알맞은 시스템 구성도 구축
            성능, 안정성, 확장성 등을 고려하되, 이를 표현한 글은 자세하고 정량적으로 표현
            ex) 10만명 이상의 동시 사용자 처리가 가능하며 한 시간 이내에 100만명까지 추가 확장이 가능하며, 백업을 위한 핫 사이트가 구비되어 있습니다.

          • 제안 요청서 분석
            제안 요청서는 고객이 제안을 요청하는 문서로, 고객의 요구와 배경, 목적, 목표 시스템 등이 적혀 있다.

          • 논리적 완결성
            내용과 순서가 뒤죽박죽이고, 서로 떨어져 있다면 독자 입장에서 페이지를 옮기면서 읽어야 하며, 가독성과 이해성이 떨어지며, 심사위원은 곤혹스러워 할 것이다.

          고객 및 경쟁사 관련 팁

          • 고객이 원하는 문제에 대해 기술적으로 우위일 시, 경쟁사와 비교하여 제안
            ex) 네비게이션 앱 솔루션에서 인공지능 추천을 구현 가능할 시 비교
            자사 A사 B사
          운전 이력 기록 O O O
          운전 이력 분석 O O X
          운전 시간 분석 O X X
          운전 취향 분석 O X X
          맞춤형 추천 O X X

          단, 너무 혁신만 강조하면 실험적이라고 느낄 수 있으므로, 안정성을 기본으로 강조하자.

          • 고객이 원하는 문제에 대해 기술적으로 힘들면 동감하고 다른 방안을 제시
            ex) 인공지능 경로 추천 기능은 우리 A사는 다음과 같은 이유로 추천 드리지 않으며, 설문 방식을 추천 드립니다.
            - 충분한 학습 시간이 필요하다. 설문 방식은 5분이면 가능
            - 인공지능이 추천한 경로가 마음에 들지 않아도 학습으로 인해 변경 불가
            - 돌발적이고 이상한 추천 상황이 생길 수 있음

          • 고객이 사소하다고 느끼는 문제에 대해 기술적 우위 시, 문제를 중대하게 보도록 설득
            ex) 인공지능 경로 추천 기능은 최근 선지사를 중심으로 도입되고 있는 추세이며, 차별화 기능을 통해 미래를 대비해야 합니다. (추가로, 네비게이션 회사의 인공지능 관련 기사나 도표를 첨부한다)

          • 고객이 사소하다고 느끼고, 기술적으로 힘들면 경쟁사 전략에 따라 대응
            ex) 경쟁사가 고객에게 문제를 중대하게 보도록 설득한다면, 심사위원에게 해당 문제에 대한 상담이나 질문이 들어올 수 있으므로 미리 준비

          요구 사항 관련 팁

          • 요구 사항을 단순히 분석하지 말고 제시
            고객은 자기가 원하는 제품에 대해 정확히 모른다.
            따라서 모순되거나, 비현실적이거나, 사용자 경험에 나쁘거나, 심각한 결함이 있는 요구 사항을 요구할 수 있다.
            이에 대한 대안을 제시하여 설득할 수 있어야 한다.

          • 변화하는 요구 사항에 대비
            고객의 요구 사항은 자주 바뀌므로, 미팅과 테스팅 단계를 자주 잡도록 하자.

          • 상품 기획 이론 카노 모델에 의한 고객의 만족을 높이는 요구 사항 제시

            • 고객이 당연하다고 예상하고 기대하는 기본 기능
              ex) 로그인, 회원가입, 게시글 쓰기
              • 요구 불 충족 시 고객 만족도 대폭 저하 ▼, 요구 충족 시 고객 만족도 소폭 증가 △.
            • 고객이 잘 인지하지 않으나 보통 존재하는 기능
              ex) 로딩 시간 감소, 보안 관련 설정
              • 요구 충족 시 고객 만족도 보통 상승 ↑, 요구 불충족 시 고객 만족도 보통 감소↓
            • 고객이 기대하지 않았으나 특별한 기능
              ex) 스마트폰 지문, 홍채 인식 로그인
              • 요구 충족 시 고객 만족도 대폭 상승 ▲, 요구 불충족 시 고객 만족도 소폭 감소 ▽

          기술 블로그

          기술 저널 글쓰기 팁

          • 주제 의식 버리고 소재 의식 글쓰기
            • 주제 의식 : 추상적 가치에 대한 생각(권선징악, 자존감, 사랑, 자본주의)
            • 소재 의식 : 특정한 대상이나 상황에 대한 자기만의 관점이나 해결 방안
              좀 더 담담하고 상황에 대한 해결 방안이나 설명에 대해 쓰자

          • 자기 수준 글쓰기
            모든 독자를 위해 글을 쓰지 말자. 기술 저널은 보통 인기를 끌기 위해 쓰는 것이 아니다.
            독자의 대부분인 개발자들은 어려운 용어를 잘 이해할 수 있을 것이며, 굳이 설명하려면 위키 문서 등을 링크해두자.

          • 재미있게 글쓰기
            글의 기교는 글을 아름답게 만들고 쉽게 읽힌다.
            재미있는 글은 인기와 반응이 좋아지고, 그에 따라 당신의 의욕도 늘린다

          • 협업 해서 글쓰기, 페어 글쓰기 해보기

          • 회사의 기술 블로그는 사내 문화를 반영하고, 노하우를 체계적으로 축적할 수 있다.

          • 머릿말과 맺음말은 맨 마지막에 쓰기
            주로 서비스 설명, 개발의 필요성, 느낀 점 등을 적음

          기술 블로그 글의 종류

          저(Essay)

          직접 경험하고 실험한 과정이나 결과
          ex) 개발기, 도입기, 적용기
          ex) Dagger 적용기, 분산 웹 캐시 개선 과정, TensorFlow를 활용한 네이버 쇼핑의 상품 카테고리 자동 분류

          • 목차를 잘 잡으면 쓰기 쉽지만 목차를 잡기 어렵다
            ∵ 개발은 다차원의 병렬적으로 진행되지만 글은 1차원 단방향으로 써야 하기 때문에

          • 따라서 성공한 최종 루트를 기준으로 다른 루트를 조금씩 언급하며 문제 해결이나 팁으로 정리하며 쓰면 된다.

          술(Dictionary)

          어떤 것을 분석하여 의미를 풀이하고 해석한 것
          ex) 기술 소개, 용어 분석, 에러 해결 방법
          ex) GET과 POST의 차이, MySQL 1175 에러 해결 방안, MySQL Ascending index vs Descending index

          • 원전의 내용을 쉽게 풀어쓰고 비교하는 것으로도 쓸 수 있다.
          • 추가적으로 직접 실험한 결과나 적용 결과를 보여주어도 좋다.

          편(Tutorial)

          산만하고 복잡한 자료를 편집해 질서를 부여한 것
          ex) 프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰
          ex) ES2015 단위 테스트 환경 구축하기, Ubuntu의 apt-get을 이용한 패키지 설치, 예제 코드로 알아보는 React

          • 시간 순서로 하나씩 나열해 내용을 쓴 후, 단계로 묶어서 요약하면 된다.
          • 추가로 태그와 HTML, 구조화된 글쓰기로 가독성을 늘릴 수 있다.

          집(Collection)

          여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것
          ex) 명령어 모음, 팁, 00가지 규칙
          ex) 자바스크립트 정규표현식 코딩 팁, 프로그래머를 위한 12가지 규칙, 기술 인터뷰 질문 모음

          • 타인이나 본인의 견해와 자료를 모아 일정 순서와 단계로 엮으면 된다.