독자를 위한 글쓰기
독자는 현장에 없었습니다. 그들은 해당 분야는 알지만 여러분의 프로젝트는 모르며, 훑어 읽습니다. 단어 선택 시 plain-words를 적용하세요.
- 기존 논문, 보고서 또는 페이지 편집, 교정 또는 정리: 아래 규칙을 체크리스트로 삼아
references/editing-pass.md를 따르세요. - 논문 작성 또는 편집:
references/paper.md도 함께 읽으세요.
순서
- 발견한 사실을 먼저 제시하세요: 무슨 일이 일어났는지, 그리고 그 규모는 어느 정도인지. 새로운 아이디어나 능력을 제목으로 삼으세요; 비교는 그것이 기여인 경우에만 주도합니다. 소개가 필요한 경우에만 문제를 먼저 제시하세요; 일반적인 문제는 피하세요. 프로젝트 이력이나 실행한 내용을 나열하지 마세요.
- 제목은 주장을 진술합니다: 보고서에서는 ("가격 분석"이 아닌 "저렴한 요금제가 더 많이 팔린다"); 긴 보고서는 발견된 사실의 번호 목록으로 시작합니다.
- 요약은 높은 수준을 유지합니다: 발견된 사실을 말로, 독자가 인용할 숫자를, null 값을 말로, 각각이 중요한 이유를 설명하세요. 요청된 길이에 맞추세요. 독자가 기억할 명확한 주장으로 끝내세요.
- 이메일 및 핸드오프: 간단한 의사 결정 목록: 무엇을 할지, 각 수정 사항의 난이도, 수동 작업이 가장 적게 필요한 옵션.
- 본문은 독립적으로 서야 합니다. 모든 용어와 비교 대상을 본문에서 처음 등장할 때 정의하고, 부록에서 처음 정의하지 마세요. 긴 보고서는 짧은 용어집으로 끝냅니다.
내용
- 모든 숫자에 비교 대상을 제공하세요: "25.6% 정확도 (기준은 10%)".
- 작은 발견이라도 그 규모를 말하세요.
- 발견당 실제 예시 하나를 보여주세요. 사례 연구, 놀라운 점, 확인된 부정적 결과는 그대로 두세요.
- 방법은 처음 나오는 곳에서 한 번 설명하세요: 방법에 대한 한 줄; 독자가 묻거나 오해할 수 있는 경우에만 이유를 설명하세요. 모집단이나 분모를 정의하는 제외 사항을 공개하세요; 일상적인 선택을 변호하지 마세요.
- 콘텐츠 경고나 자신의 과정에 대한 메모는 하지 마세요: 매체나 사용자가 요청하지 않는 한. 결과를 본 후 임계값이나 하위 집합을 선택했다면, 규칙을 명확하게 한 번만 진술하세요.
- 한계는 그것이 제한하는 주장 옆에 한 번만 진술하고, 독자가 믿어야 할 것을 바꾸는 경우에만 그렇게 하세요. 결과를 정의하는 조건은 그대로 두세요 ("2024년에만"). 강건성 검사에서 단 한 번의 근접 실패는 헤드라인을 낮추지 않습니다; 반전은 그렇습니다.
- 헤지(모호하게 말하기) 대신 과잉 주장을 좁히세요: 확실한 부분은 유지하고, 불확실한 부분은 버리세요.
- 발견을 훼손하지 마세요. 데이터가 보여주는 것 이상을 양보하지 마세요. 독자가 믿어야 할 것을 바꾸지 않는 한, 아무도 요구하지 않은 대조를 추가하지 마세요. 점검이 이야기를 약화시킨다면, 헤지하거나 버리기 전에 분석을 수정하거나 확장하는 것을 제안하세요; 분석을 직접 변경하지 마세요.
- 빽빽한 블록은 피하세요. 단락은 한 가지 요점을 전달하며 한 번, 빠르게 읽을 수 있어야 합니다. 발견이나 조건을 쌓는 단락은 나누세요; 일련의 숫자는 표나 목록으로 넣으세요. 항목이 병렬일 때 글머리 기호를 사용해도 좋습니다.
- 하나의 이야기. 부수적인 이야기는 버리세요. 2차 점검과 예외는 본문에서 한 문장으로 처리하고, 자세한 내용은 부록으로 보내세요.
- 같은 것은 같은 것과 비교하세요. 다른 데이터셋이나 사람의 숫자는 각각 고유한 문장이나 표를 사용하세요. 마치 하나가 다른 하나를 초래한 것처럼 나란히 배치하지 마세요.
- 모든 것은 스스로를 정당화해야 합니다. 모든 단어, 문장, 단락, 목록 항목, 섹션, 표 열, 그림 패널, 캡션 절은 독자가 믿는 바를 바꾸거나 읽는 방식을 바꿔야 합니다. 각각에 대해 물어보세요: 그것 없이 독자는 무엇을 잃을까? 아무것도 없다면, 잘라내세요; 압축하지 마세요.
- 각각은 한 번만 말하세요. 숫자는 표나 텍스트 중 한 곳에만 있어야 하며, 둘 다에 있으면 안 됩니다; 본문이나 부록 중 한 곳에만 있어야 하며, 둘 다에 있으면 안 됩니다. 발견은 전체 내용이 한 번 명시됩니다; 초록, 서론 및 요약은 핵심 숫자만 반복합니다.
- 출처에 없는 것은 추가하지 마세요. 인용이나 결과를 절대 지어내지 마세요; 저자를 위해 표시된 자리 표시자를 남겨두세요.
그림과 표
- 각 패널은 텍스트가 잘 전달하지 못하는 한 가지 요점을 전달합니다. 측정 지표, 더 나은 방향, 기준선을 명확하게 표시하세요.
- 코드 대신 실제 이름; 가장 간단한 차트; 제목이 있는 축; 캡션 및 텍스트와 일치하는 하나의 레이블 체계. 명명하는 계열 옆에 직접 레이블을 배치하세요.
- 모든 하위 집합을 보여주거나, 그 집합을 선택한 규칙을 명시하세요.
- 보고서에서 그림 제목은 보여지는 내용을 말합니다. 캡션은 읽는 방법을 말하며 방법을 반복하지 않습니다.
넘기기 전에
독자의 입장에서 읽으세요. 각 문장에 대해: 그들이 놓칠까요? 각 숫자가 "무엇과 비교해서"라고 말하고 있나요? 그런 다음 plain-words를 실행하세요. 어떤 숫자도 변경하지 마세요. 무언가 빠졌거나 두 숫자가 일치하지 않으면, 저자에게 알리고 스스로 채우지 마세요.