[SECTION 5] <Final Project> 프로젝트 회고와 평가

# 프로젝트 README 작성

왜/어떻게 글을 써야 하는가?

왜 글을 써야 하는가?

- 프로젝트와 관련하여 글을 쓰는 것은, 개인의 성과를 드러내고 이를 통해 나의 역량과 가능성을 보여주는 데 그 목적이 있으며 이러한 기록은 그 자체로도 훌륭한 이력이 됨

 

어떻게 글을 쓸 것인가?

Divio Technologies의 문서화와 관련된 레퍼런스에 따른 기술 문서 작성의 네 가지의 다른 접근법

• 튜토리얼
• How-To 가이드
• 설명
• 레퍼런스

 

프로젝트 문서화

- 프로젝트를 GitHub 등에 배포하고 난 후에, 반드시 필요한 것은 README.md 파일

README 파일이 포함하는 내용

1. 프로젝트 설명

- 설명은 글을 읽는 사람이 프로젝트에 대해 이해할 수 있도록 작성되어야 함

- 여기서는 프로젝트 그 자체에 대한 이해를 목적으로 함

- 설명에는 프로젝트 제목과 함께 그 맥락이 담겨야 하며 맥락이란, 이 프로젝트를 시작하게 된 이유, 배경과 같은 것들을 의미함

- 설명에는 다음을 포함할 수 있음

• 무슨 문제를 풀고자 하는가
• 이 아키텍처를 활용하는 사용자는 어떤 상황에 놓여있는가
• 이 아키텍처는 어떤 기술을 활용하여 작동하는가
• (추가적으로) 이러한 설계를 하게 된 이유나, 기술적인 제약에 대한 내용을 쓰는 것도 포함할 수 있음

- 여기에는 독자에게 기술 그 자체를 가르치거나, 레퍼런스를 제공할 필요가 없음

2. How-To 가이드

- How-To 가이드는 문제를 해결하기 위한 목적을 갖고 있음

- 프로젝트의 How-To 가이드를 만들어야 하는 경우 에는, 어떤 문제를 푼다기보다는, "성공적인 아키텍처 배포"라는 목적을 달성하는 데 중점을 두어서 쓰면 됨

- 다음과 같은 원칙을 가지고 문서를 쓸 수 있음

• 순서를 명시해야 함
  • 이러한 부분은 튜토리얼과 비슷하지만, 글을 읽는 사람이 초보라고 가정할 필요는 없으며 어느 정도 기술 스택과 관련한 지식이 있는 사람이 글을 본다고 생각하면 됨
• 결과가 어떠한지 명시해야 함
  • 목표를 달성했을 때, 잘 작동된다는 것을 어떻게 확인할 수 있는지 안내해야 함

- 여기에서는 콘셉트 그 자체를 설명할 필요는 없음(설명이 하는 역할)

- 한편, How-To 가이드는 적당한 유연성을 발휘할 필요가 있음 (ex) 디렉토리 이름이라던지, 프로그래밍 언어 버전이 조금 다를 수 있음을 염두해야 함 따라서, 모든 것을 완전히 설명하려고 하지 않아도 됨

 

문서화 예시

GitHub README 문서

- 처음으로 프로젝트 설명이 개요로 등장

- 더 설명이 필요한 부분에는 Learn more about...으로 안내

- 추가적으로 How it works를 통해 부족한 설명을 보충

- 나머지 부분은 How-To 가이드 이 GitHub 리포지토리를 이용해서, 배포를 성공적으로 하는데 그 목적을 둠

 

# 기술 블로그 작성

글감 찾기

기술 블로그의 주제

기술 블로그의 주된 주제

1. 내가 이 프로젝트를 통해 새롭게 이해한 바
   • 문서화의 네 가지 접근법에 따르면, 설명에 가까움
   • 즉 "설명"은 글쓴이의 이해가 온전히 반영되지 않는다면 매우 쓰기 어려움
   • 어떤 기술이나 개념에 대해 얼마나 깊게 이해하는지가 낱낱이 드러남
2. 내가 이 프로젝트를 통해 해결한 문제에 대한 기록 및 회고
   • 문서화의 네 가지 접근법에 따르면, How-To 가이드에 가까움
   • How-To 가이드의 경우 글을 읽는 독자가 "글쓴이의 이해 수준"을 파악할 수는 없음
   • 그저 문제가 해결되거나, 작동되기만 하면 되기 때문에, 글쓴이의 이해 수준이 드러나지 않는 것

- 이러한 글을 쓰는 것은 단순히 문제를 해결할 줄 아는 엔지니어를 넘어, 기술을 이해하고 사용하는 엔지니어라는 것을 증명하는 도구 기술 블로그 글은 스스로를 어필하는 매우 중요한 수단

 

이해한 것을 바탕으로 블로그 글 쓰기

1. 특정 문제로부터 시작하기

- 에러 메시지나 이해하기 어려웠던 작동 방식 등을 통해 왜 그러한 에러 메시지가 나왔는지, 왜 작동이 되었는지/되지 않았는지를 구체적으로 설명

- 문제를 통해 만들어지는 이러한 류의 글은 다음과 같은 제목으로 표현될 수 있을 것 

• 상황: Firehose에 데이터를 보냈지만, 즉시 전달되지 않는 스트림
  • 글 제목: Firehose를 통해 이해한 스트림과 버퍼

 

2. 호기심과 의문으로부터 시작하기

- 기술 그 자체에 대한 호기심

- 쓰라고 해서 쓰긴 했는데, 왜 써야 하는지 궁금한 기술 스택과 같은 경우

- 연구가 결론이 나면 좋겠지만, 꼭 그럴 필요는 없으며 조사한 것만으로도 충분

- 믿을 만한 사례를 찾아보고 첨부하여 이해한 바를 마무리해도 좋음

- 의문 그 자체가, 블로그 글 제목으로도 활용될 수 있는 예제

• 글 제목(의문): OpenSearch가 위치 정보를 수집하는 용도로 정말 적합할까?

- 위 글의 경우 OpenSearch의 특징과 활용 사례를 나열하고, 이를 바탕으로 자체적인 결론을 내리면서 마무리 지을 수 있음

 

목차 만들기

목차 만들기

1. 목적과 상황에 대한 설명
   • 문제 상황을 설명함 애초에 글의 도입부를 에러 메시지에 대한 내용으로 시작해도 좋음
   • 비슷한 문제를 겪은 사람들의 유입이 보다 더 많아질 것
2. 내가 이해한 바와 시도한 방법
   • 시도가 중요함 한 번에 정답을 찾아내면 좋겠지만, 그렇지 않아도 좋음
   • 문제를 좁혀나가는 능력을 대중에게 알리는 좋은 방법
3. 분석
   • 실험에 따른 결과를 분석해야 함 문제 해결이 아니라, 되려 다른 문제 상황으로 빠지는 경우가 있음
   • 이 때는 문제 해결의 키가 다른 곳에 있었다는 증거이며 이런 분석은 글을 보다 더 풍성하게 만듦
4. 원인 발견과 해결 방법
   • 말 그대로 해결 방법을 적는 과정
5. 새롭게 알게 된 사실
   • 새롭게 알게 된 개념을 설명
   • 결국 이 내용이 글의 중심 주제 글 제목에 중심 주제가 포함되어 있는지를 다시 한번 확인할 것

 

 

글을 쓸 때 주의해야 할 점

글을 쓸 때 주의해야 할 점

1. 모르는 것은 모르는 채로 둘 것
   • 어설프게 설명하는 것은 금물
   • 잘못된 정보를 전달하면 글쓴이의 신뢰가 하락하므로 "이 부분은 더 공부가 필요하다"라고 마무리 짓는 게 좋음
2. 너무 큰 주제를 다루지 않음
   • 내가 다루려는 주제가 생각보다 훨씬 큰 주제일 수도 있음
     • 예를 들어, 그저 HTTPS가 궁금해서 연구를 시작했다가, TCP 프로토콜 및 암호화 알고리즘까지 가버리면 결코 이 글은 하나의 글로는 완성되지 않을 것
   • 이럴 경우 "이것에 대해서는 이 레퍼런스에 더 잘 나와있다" "이 내용은 주제에 벗어나므로 생략한다"와 같이 적당히 끊어주는 게 좋음
3. 글을 쓰는 목적을 늘 염두함
   • 글을 통해 누군가를 가르치려고 하는 것이 아님
   • 처음 글감을 고를 때는 내가 겪은 문제 또는 의문로부터 시작하겠지만, 결국 이 글은 "내가 이러이러한 개념에 대해 이해를 하고 있다"는 것을 대중에게 드러내기 위해 쓰는 것
   • 어떤 주제에 대해 얼마만큼 이해하고 있는지 누군가 물어본다고 가정하고 결국 간결한 몇 마디 문장으로 개념에 대한 이해를 요약해서 말해야 함
   • 스토리텔링이야 길게 써도 좋지만, 결국 핵심은 네다섯줄 정도로 끝낼 수 있음

 

글 완성하기

퇴고와 발행

- 앞서 글감과 목차를 만들고 나면, 그다음은 쉬워짐 여기 퇴고와 발행과 관련한 부분도 참고하면 좋음

• 내가 블로그에 글을 쓰는 과정 - Outsider's Dev Story

기타 추천 자료

• 좋은 기술 블로그를 만들어 나가기 위한 8가지 제언

 

 

개인 평가 방식

진행 방식

• 결과물은 프로젝트 내용을 바탕으로 한 기술 블로그 작성 및 발행
• 평가는 프로젝트 결과와 기술 블로그 작성 내용을 바탕으로 한 인터뷰 형식으로 진행됨

기술블로그 작성에 포함해야 하는 내용

• 아키텍처 구성 중 가장 어려웠던 점
• 새롭게 알게 된 지식