Show GN: SymvaCAS – CAS, 그래프, 통계, 확률, Python을 한곳에 넣은 오픈소스 공학용 계산기

요약

소프트웨어 개발 블로그를 효과적으로 작성하기 위해 독자의 수준을 고려한 핵심 내용 전달과 친절한 용어 설명의 중요성을 강조합니다.
딱딱한 문체 대신 개인적인 목소리를 담아 쓰고, 모바일 환경에서의 가독성을 확보하는 등 독자 중심의 글쓰기 방식을 제시합니다.

개발 블로그에서 가장 흔한 실수는 본론에 도달하기까지 너무 오래 걸리는 것임. 제목과 첫 세 문장 안에 누구를 위한 글인지, 읽으면 무엇을 얻는지 알려야 함
독자가 자신과 같은 지식을 가졌다고 가정하지 않아야 함. 실제 친구나 동료를 기준 독자로 정하고, 그 사람이 아는 용어와 모르는 용어에 맞춰 설명을 점검함
생소한 용어에 링크만 붙이거나 이전 편을 읽으라고 요구하지 말고, 현재 글만으로 이해할 수 있는 최소한의 설명을 제공해야 함
진지하게 보이려고 딱딱하게 쓰기보다 평소 말하듯 자기 목소리로 써야 함. AI에 글쓰기를 맡기며 획일적인 글이 늘수록 개성 있는 문체가 중요해짐
좋은 내용도 읽기 불편하면 소용없음. 모바일에서 본문이 화면을 넘치지 않는지, 글꼴과 색상 대비가 읽기 편한지 게시 전에 확인해야 함

장황한 도입부와 불필요한 서문

소프트웨어 블로그에서 가장 흔한 실수는 핵심에 도달하기까지 너무 오래 걸리는 것임
- 배경 이야기, 역사적 맥락, 떠오르는 생각을 늘어놓는 것은 쓰는 사람에게 즐거워도 독자에게 흥미롭지는 않을 수 있음
- 독자는 다른 수많은 글을 선택할 수 있으므로, 얻을 것이 있다는 기대 없이는 20분을 투자해 끝까지 읽지 않음
제목과 첫 세 문장 안에 두 질문에 답해야 함
- 이 글은 나 같은 사람을 위해 쓰였는가?
- 읽으면 어떤 이익을 얻는가?
읽을 이유는 새로운 기술이나 개념, 새로운 시각, 재미있는 이야기나 신랄한 비판 등 무엇이든 될 수 있지만, 반드시 무언가를 제공해야 함
if got, want: 더 나은 Go 테스트를 작성하는 간단한 방법은 잘 알려지지 않은 Go 테스트 패턴을 30초 안에 배울 수 있다는 도입으로 대상 독자와 가치를 곧바로 알림
매력적인 도입을 썼더라도 부제, 자기소개, 이미지, 유명인의 인용문이 읽는 흐름을 방해할 수 있음
- 이런 요소를 넣을 수는 있지만, 독자의 제한된 집중력을 소모하고 계속 읽도록 설득할 기회를 줄인다는 점을 고려해야 함

독자가 무엇을 아는지 과도하게 가정하지 않기

새로운 개념은 독자에게 익숙한 대상과 비교하면 이해하기 쉽지만, 무엇이 익숙한지 먼저 판단해야 함
- Jellyfin은 Netflix 같은 스트리밍 서비스이되, 오픈소스이고 사적으로 운영해 시청 습관을 감시받지 않는다는 식으로 소개할 수 있음
Docker 입문 글에서 Linux cgroups의 프런트엔드나 *BSD jails의 Linux 버전이라고만 설명하면, 해당 용어를 모르는 독자를 놓침
- Docker를 배우려는 개발자가 cgroups, jails, *BSD를 안다는 보장은 없으며, Linux조차 모를 수 있음
사전지식에 대한 가정을 줄이려면 Docker가 어디서 실행해도 일관되고 재현 가능한 환경을 갖도록 앱을 패키징하는 도구라는 식으로 설명해야 함
- 사람이 읽을 수 있는 텍스트 파일에 앱의 환경과 의존성을 정의함
- 여러 팀이 수년간 수정하더라도 요구사항이 파일에 남아 작동 방식을 파악할 수 있음
실제 친구나 동료 한 명을 기준 독자로 정하고, 그 사람이 아는 용어와 모르는 용어를 목록으로 만들어야 함
- 초안을 다시 읽으면서 기술 용어가 나올 때마다 기준 독자가 이해할 수 있는지 확인함
- Tyler Cipriani는 The future of large files in Git is Git을 편집하는 과정에서 이 목록과 초안의 가정을 비교하는 방식이 매우 인상적이었다고 평가함

설명을 외부 링크에 떠넘기지 않기

생소한 용어에 링크만 붙이면 독자는 단어 하나를 이해하려고 읽던 흐름을 끊고 다른 사이트로 이동해야 함
FreeBSD 매뉴얼의 방화벽 장은 훌륭한 자료지만 약 2만 단어에 달함
- 데이터베이스에 외부 트래픽이 도달하지 못하도록 방화벽 규칙을 설정하라는 문장에 이 링크만 붙이면 독자에게 막대한 읽기 부담을 넘기게 됨
본문에 이해에 필요한 최소한의 설명을 넣어야 함
- 방화벽은 호스트와 네트워크가 앱과 통신하는 방식을 제한하는 시스템임
- 데이터베이스 서버로 들어오는 요청을 앱 서버에서 온 경우에만 허용하도록 규칙을 설정하면 웹 앱의 보안을 강화할 수 있음
링크는 필수가 아닌 추가 자료여야 함
- 대상 독자가 링크를 클릭하거나 툴팁 위에 마우스를 올리지 않고도 처음부터 끝까지 글을 이해하고 즐길 수 있어야 함

후속편이라는 전제로 시작하지 않기

이전 편에서 배운 내용이나 직접 만든 용어를 독자가 기억한다고 가정하면, 읽기 시작하기도 전에 추가 과제가 생김
대부분의 독자는 이전 글을 읽지 않았다고 가정해야 함
- 이전 글을 참조해도 되지만 도입부터 그 이야기로 시작하지 않아야 함
- 이전 글에 링크할 때는 전체를 다시 읽도록 요구하지 말고 현재 글에 필요한 부분을 요약해야 함
처음부터 만든 취미용 운영체제처럼 여러 편이 필요할 법한 주제도 있지만, 대부분의 후속 글은 3% 정도만 더 노력해도 독립적인 글로 만들 수 있음

과도한 격식 대신 자기 목소리로 쓰기

진지하게 받아들여지려면 딱딱하게 써야 한다는 생각을 버리고 평소 말하듯 써야 함
- “이 프로젝트의 전체 수명 동안 팀원들과 본인에 의해 여러 정적 분석 도구가 활용되었다”보다 “이 프로젝트에서 정적 분석기 몇 개를 써봤다”가 자연스러움
- 소프트웨어 개발 독자는 법률 문서 같은 문체를 기대하지 않음
개발자들이 글쓰기를 AI에 맡기면서 소프트웨어 블로그가 밋밋하고 획일적으로 변하고 있으며, 독자는 개성 있는 글을 원함
Joel Spolsky의 The Perils of JavaSchools는 친구에게 점심시간에 이야기를 들려주는 듯한 문체의 사례임
- 고등학교 때 Apple II에서 BASIC으로 Pong을 만들던 학생들이 대학에서 포인터를 만나 좌절하고 정치학으로 전공을 바꾼다는 이야기를 편하고 꾸밈없이 풀어냄
- Kathy Sierra, Terence Eden, Raymond Chen의 글에서도 똑똑해 보이려 하기보다 자기답게 말하는 스타일을 볼 수 있음

모바일 화면 넘침과 읽기 어려운 글꼴

모바일에서 본문이 화면을 넘어가 좌우로 스크롤하며 읽어야 하는 상황을 피해야 함
- 데스크톱 크기를 고집하는 이미지나 코드 조각이 페이지 전체 레이아웃을 망가뜨리는 경우가 흔함
게시 전 데스크톱 Firefox와 Chrome의 모바일 미리보기로 화면 넘침과 일반적인 렌더링 문제를 확인해야 함
- 방문 통계상 이 글 페이지의 모바일 독자는 25%, 개인 블로그의 모바일 독자는 35%임
읽기 쉬운 글꼴과 색상을 선택하고, 밝은 회색 배경에 짙은 회색 글자를 쓰는 식의 낮은 대비를 피해야 함
- Firefox와 Chrome에는 대비가 낮은 텍스트를 찾아주는 내장 도구가 있음
글꼴 선택이 어렵다면 Braille Institute의 무료 글꼴 Atkinson Hyperlegible 을 사용할 수 있음
- 시력이 좋지 않은 독자도 편하게 읽을 수 있는 글꼴임