refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

2026-09-04 18:56:01 +09:00
parent 4b9e7148b5
commit 43bccd08a8
121 changed files with 2861 additions and 534 deletions
@@ -0,0 +1,72 @@
+# Editorial Rules From Korean Engineering Writing
+
+These rules were distilled from multiple public Korean engineering blogs. They describe broad technical-writing habits, not a target author's style.
+
+## Lead with the engineering situation
+
+When a draft spends several paragraphs defining a technology before stating why it appears, move the concrete service/code situation, constraint, failure, or measurement earlier. Keep only the concept explanation needed to follow that situation.
+
+Do not fabricate a `background story` merely to create an opening.
+
+## Keep constraint → requirement → choice connected
+
+A credible choice is usually readable from its constraints. When the source contains requirements, put them close to the solution they rule in/out. Do not add generic benefits such as maintainability, scalability, security, or performance unless the source demonstrates that they mattered here.
+
+## Write the observed chain, not a summary slogan
+
+Prefer:
+
+```text
+input/condition → state change → observable result → evidence-backed cause
+```
+
+over a paragraph that repeatedly says the architecture has a problem or responsibility.
+
+## Make metrics carry context
+
+Keep the dataset, request shape, time window, before/after condition, or comparison axis next to a number. Do not turn a measurement into an adjective such as `크게`, `압도적으로`, `획기적으로` unless the source justifies that interpretation.
+
+## Use tables only when there is a real axis
+
+Good table candidates:
+
+- requirement → reason;
+- before → after;
+- option → same comparison dimensions;
+- environment → observed result;
+- defined → not defined verification coverage.
+
+If every row needs a paragraph of caveats, prose may be clearer.
+
+## Let section lengths differ
+
+Human engineering reports spend space where the difficult reasoning occurred. A two-line setup next to a long failure analysis is fine. Do not normalize all sections to the same number of paragraphs or bullets.
+
+## Do not manufacture first person
+
+Public engineering blogs often use first person because their authors participated in the project. A code-derived document has no such license. Use `코드에서는`, `실행 결과에서는`, `이 구성에서는`, or the concrete component name unless source material contains a real first-person account.
+
+## Preserve limitations
+
+Do not polish away `확인하지 않은 것`, `운영에서는 별도 검증`, failed attempts, excluded scope, or competing explanations. Those boundaries make the technical claim credible.
+
+## Explain concepts at the point of use
+
+Introduce PKCE, LCP, Kafka rebalance, keyset pagination, etc. only to the depth needed for the next piece of reasoning. Avoid detached encyclopedia sections unless the record itself is a Reference that requires them.
+
+## Prefer direct headings over forced questions
+
+Use headings that name the actual event, boundary, measurement, or change. Do not convert every heading to `왜 ...일까?`, `...해보자`, or rhetorical copy. A question heading is appropriate only when the section genuinely resolves that question.
+
+## Vary rhythm by content, not by randomization
+
+Do not mechanically alternate short and long sentences. Instead:
+
+- keep a consequence close to its cause;
+- split a sentence when it contains two independently important actions;
+- keep a short sentence when a measured fact can stand alone;
+- combine fragments that only make sense together.
+
+## Remove AI scaffolding
+
+Review expressions such as `중요한 점은`, `핵심은`, `결국`, `즉`, `다시 말해`, `이 지점에서`, `한편`, `정리하면`. They are not forbidden, but repeated use often means the previous sentence already said the same thing. Delete the scaffold before rewriting the substance.