73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
# 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.
|