한 장 보고서의 정석

책을 선택한 이유

도큐사우루스로 문서를 작성하고 버전을 관리하며 이전에 작성한 문서들을 다른 개밸자가 작성한 문서들과 비교해보니 문서의 흐름이나 문장의 일관성의 수준이 다른 블로그에 비해 약간 떨어진다는 느낌을 받았다. 내용이 어색한 문서는 독자의 경험을 떨어뜨리기 때문에 이를 보완하기 위해 추천받은 책을 읽어보았다.

핵심 요약

전체 문서를 도식화 하기 위해서 가장 중요한 것은 가장 중요한 내용을 담아서 압축하는 것이다. 코드와 마찬가지로 내용이 길어질수록 핵심과 멀어질 수 있으며, 이는 기존 목적을 상실하게 되거나 기능적 오류를 야기할 수 있다.

정보를 전달하기 위한 문서는 의식의 흐름대로 저절로 이해되는 구조로 작성해야 하고 정확한 정보를 효과적으로 전달해야한다. 이 책에서 그 방법을 3가지 질문 프로그램을 기술하고 있다.

• 결론 정리 질문 (What first)
  So what? → Why so? → How?

ex) 

So what? → "코드 리뷰 자동화는 개발 효율성을 높인다." (결론)

Why so? → "반복적인 리뷰 작업을 줄이고, 
코드 품질을 일정 수준 이상으로 유지할 수 있기 때문이다." (이유)

How? → "Lint, SonarQube 등의 정적 분석 도구를 도입하고, 
PR(풀 리퀘스트) 자동 검사를 설정한다." (방법)

결론을 먼저 제시하면 자연스럽게 질문을 유도하고 해결 방법을 제시할 수 있다. 근거가 결론을 받쳐줘야 하는 문장이기 때문에 이후의 논리가 따라주지 못한다면 사용자의 이해를 도울 수 없다.

• 요점 정리 질문 (2What)
  What? → so What?

ex)

What? → "우리 팀은 코드 문서화가 잘 되어 있지 않다." (사실)

So what? → "신입 개발자나 신규 기능 개발 시, 이해도가 낮아져
유지보수 시간이 증가한다." (중요성)

사실을 먼저 제시하고 왜 중요한지 설명하는 방법이다. 현 상황에 대한 적용점을 제시해야 하며 현상 나열만이 가득한 문장은 현 상황의 이해를 도울 수는 있어도 방법을 제시하지 못하기 때문에 전달력이 떨어진다.

• 제안 정리 질문 (3W)
  Why? → Why so? → What?

ex)

Why? → "너는 좀 피곤해 보이는구나." (문제 제기)

Why so? → "맞아 나는 좀 피곤하긴 해." (원인 분석)

What? → "그거 간 때문이야. 간이 피곤할땐 우루사를 마셔." (제안)

원인과 관련된 문제를 먼저 제시하고 답을 이끌어나가는 방법이다. 왜 이런 일이 일어났는지 자연스러운 문장을 만들어 해결을 위한 의견을 제안하기 위해 사용되는 방법이다.

구조 정리

사용자가 궁금해 할 내용을 효과적으로 전달하기 위해 만든 문장 흐름의 체계 같은 것이다. 사용자의 목적에 따라 형태가 달라지게 된다. 여러가지 형태가 있지만 당장 사용할 것만 추려보았다.

• 계획 보고서(프로젝트 기획)
• 결과 보고서(프로젝트 회고)
• 검토 결과 보고서(문서)
• 상황 보고서(기능 개선)
• 업무 개선 보고서(주간 회고)

형식

보기 좋은 형태를 유지하기 위한 css 같은 것이다.

• 넘버링: 1,2,3 → (1),(2),(3) → 1)2)3) 과 같은 형식으로 통일하는 것이 좋다.
• 괄호: []를 사용해 항목을 나눈 후 세부 내용을 적어주면 좋다.
• 글씨 크기: 중요도에 따라 크기를 조정한다.
• 강조 색은 빨간색

문서 작성 요령

• 개조식: 핵심을 짧고 간결하게 요약한다.
• 범주화: 주제에 맞게 분류힌디.
• 쪼개기: 막연한 개념을 의미 있는 단위로 분리한다.
• 제목: 목표를 함축한 형태다.

ex) 

목표 작성 검토 사항

구체적(Specific)
측정 가능(Measurable)
달성 가능(Achievement)
결과 창출(Result)
기간 명시(Time)

• 객관적 근거: 구체적 데이터, 비교 기준, 판단 기준 필요하다.
• 명사형 정리: 조사와 종결어미를 생략한 짧고 명확한 문장이다.
• 시각 자료: 그래프 차트 등을 사용하면 이해를 돕는데 용이하다.
• 지시 확인과 중간 보고: 클라이언트 요청을 재차 확인하고 진행 상황을 보고한다.

책을 읽고 느낀 점

좋았던 점: 문서 작성시 요령을 깨우치게 되었다.

배운 점: 효과적인 정보 전달을 위해 포함되어야 할 내용을 알게 되었다.

아쉬웠던 점: 초기에 작성한 문서들이 보여주기 위한 문서가 아니라 내가 보기 위한 문서라는 것을 깨달았다.

향후 계획: 문서 작성과 회고 방식에 맞는 템플릿을 만들어 필요한 정보가 반드시 들어갈 수 있도록 할 것이다.