3.7 KiB
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:
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.