General Writing Techniques

3-minute read
Writing
Edit

Life can’t be as good as you imagine, but it also can’t be as bad as you imagine. I think people’s fragility and strength are beyond their own imagination. Sometimes, I might be so fragile that a single word can make me tear up, and sometimes, I also find that I’ve walked a long way gritting my teeth. ——Maugham’s “Boule de Suif”

Metadata 🔗︎

Before writing, briefly outline what you want to write and adjust your expression based on the different readers.

  • Goal: Make the content clear and easy to understand for readers with different backgrounds.
  • Method: For non-technical readers, try to explain complex concepts in simple language; for technical readers, you can delve into details appropriately.

Paragraph Structure 🔗︎

Each paragraph must have an opening sentence that clearly states the main idea of the paragraph.

  • What do you want to express: Clarify the topic.

  • Why is this important: Explain the significance or value.

  • How should readers utilize this knowledge: Provide practical application scenarios or suggestions.

Sentence Principles 🔗︎

  1. Unity Principle: Avoid expressing multiple ideas in a single sentence (e.g., “and this with and that”).

  2. Concise Expression: Remove redundant words to ensure clarity.

Jargon and Cognitive Context 🔗︎

  • If professional terms or jargon are involved, provide a high-quality link pointing to the relevant explanation.

  • Assume the reader knows less than you do, avoid making beginners feel confused.

  • Example:

  • Non-technical term: “JavaScript can only do one thing at a time.”

Common Problems and Improvement Suggestions 🔗︎

1. Use fewer pronouns to avoid ambiguity 🔗︎

  • Example:

  • Error: “It runs very fast.”

    • Correction: “The code runs very fast.”

2. Avoid idioms 🔗︎

  • Example:
  • Error: “We kill two birds with one stone.”
  • Correction: “We solved two problems at the same time.”

3. Express concisely 🔗︎

  • Remove redundant expressions, such as “there exists one at some place” or “there exist multiple at some place.”

  • Example:

    • Original sentence: “There are many overlaps between software and hardware.”
    • Revised: “Software and hardware have many overlaps.”
    • Original sentence: “There is no multithreading in JavaScript.”

  • Changed to: “JavaScript does not have multi-threading.”

4. Use fewer adjectives and adverbs 🔗︎

  • Examples:
    • Incorrect: “In production mode, the code runs extremely fast.”
  • Correction: “In production mode, code execution efficiency will be improved by 225%.”

5. Using Lists 🔗︎

  • Numbered List: Used for steps or processes.
  • Bulleted List: Used for parallel content.

6. Maintain parallel list structure 🔗︎

All list items should be consistent:

  • Grammar and punctuation: Uniform formatting.
  • Logical categorization: Ensure list items belong to the same category.
  • Case Rule: Maintain consistency.

Incorrect Example: 🔗︎

  • c++
  • JAVASCRIPT?
  • Rust!
  • Chocolate chip cookies

Correct example: 🔗︎

  • C++
  • JavaScript
  • Rust
  • Python

7. Use the active voice 🔗︎

  • Example:
    • Error: “The story was written by me.”
    • Correction: “I wrote a story.”

Writing Tips 🔗︎

Iterative Documentation 🔗︎

  1. Consistent Style: Choose a formal, accurate, or conversational style based on the content.

  2. Identify Target Audience: Clearly define who your readers are and their background knowledge.

  3. Take a Break Before Revising: After writing, take a break and then review, even reading the article aloud.

  4. Find Partners for Proofreading: Ask others to help check the article and identify potential issues.

Document Organization 🔗︎

  1. Content Scope: Clearly define what is included, what background knowledge readers need, and what is excluded.

  2. Short Series of Articles is Better Than Long Articles: Modular explanations are easier to understand.

  3. Theory + Practice: Combine concepts with practical applications, demonstrating how to implement them.

  4. Step-by-Step: Progress from basic to advanced levels, expanding gradually.

  5. Table of Contents: It’s best to provide a table of contents to help readers quickly locate the desired sections.

Suggested Illustrations 🔗︎

  1. Title Concise: Attract reader attention, describe key points.

  2. Moderate Information: Avoid excessive chart information, preferably with annotations.

  3. Visual Clarity: Ensure images complement text content, enhancing understanding.