This guide compiles advice and insights on technical writing, particularly for web technology and blogging, drawing from experienced professionals and personal experience.

Choosing Your Topic:

The ideal topic is one you're passionate about and personally invested in. Your enthusiasm will shine through. As Chris Coyier wisely advises: "Write the article you wish you found when you googled something." While assignment-based writing can be productive, personal connection elevates the quality.

Write While the Knowledge is Fresh:

The best time to write is immediately after learning something new. The experience is still vivid, allowing you to convey the "before" and "after" of understanding. Even jotting down quick notes about your learning process can be valuable later. Consider the "Today I Learned" (TIL) approach, as exemplified by Manuel Matuzovic.

Leverage Comparisons:

A powerful, underutilized technique is comparing new technologies to familiar ones. Rachel Andrew suggests explaining modern JavaScript techniques to someone familiar with jQuery, bridging the gap between the new and the known. This approach connects the unfamiliar to a well-understood foundation.

Crafting a Compelling Introduction:

A common pitfall is failing to clearly state the article's purpose and target audience early on. Rachel Andrew emphasizes the importance of a concise introduction that immediately clarifies the subject and intended readership. Brian Rinaldi adds that a well-written introductory paragraph can determine whether a reader continues.

Clear and Concise Titles:

Erin Kissane advocates for clear, descriptive titles, prioritizing clarity over clickbait. A clear title like "Getting Started with GraphQL, Phoenix, and React" is far superior to a vague, clickbaity one. Clarity benefits both reader comprehension and SEO.

The Art of the Outro:

Ben Halpern highlights the significance of the concluding paragraph, often the second most read section after the introduction. While a simple summary ("Tell 'em what you told 'em") is effective, a well-crafted conclusion reinforces the message and provides closure.

Enhancing Scannability:

Brian Rinaldi stresses the importance of breaking up large blocks of text to improve readability. Techniques include using subheadings, lists, relevant images and screenshots, illustrative graphics, concise videos, well-formatted code blocks, tables, and collapsible sections using <details>/<summary></summary></details>. Strategic use of design elements like spacing, color, and alignment further enhances scannability.

Active Voice and Word Choice:

Katy Decorah and Neal Whitman emphasize the importance of using active voice ("The server processes the request") instead of passive voice ("The request is processed by the server"). Avoid words like "just," which can be condescending and often unnecessary.

Maintaining Tone and Voice:

Tone (how you say something) should align with the context. A friendly, authoritative, welcoming, and thankful tone is generally suitable for technical writing. Voice (your personality) should remain consistent, even while adjusting tone for different situations.

Managing Length:

Technical writing often suffers from excessive length. Wade Christensen recommends a ruthless editing approach. While excessively short posts are also problematic, clarity and usefulness should be the primary focus, not word count. Breaking a long post into a series should only be done if the parts are thematically distinct and self-contained.

Overcoming Writer's Block:

Fear and self-doubt are common barriers to technical blogging. Max B?ck suggests publishing as soon as the essential points are covered, ignoring the "it's not ready" voice. Jeremy Keith advises against keeping drafts, as they often remain unfinished. Remember, even a small contribution can be helpful (Matthias Ott). Ali Spittel points out that even beginners have valuable perspectives.

Style and Creativity:

Sara Soueidan emphasizes that there's no single perfect writing style. Be yourself and let your personality shine through while maintaining clarity. Experiment with creative formats, like annotated conversations or video series.

Beginner-Focused Content:

While the web is filled with beginner-level content, a well-written introductory post can stand out. Clarity is valuable for all skill levels.

Real-World Examples vs. Abstraction:

Christine emphasizes the importance of real-world examples to illustrate complex concepts. However, avoid examples that compromise clarity. Abstraction can be powerful when used effectively.

The Benefits of Blogging:

Blogging enhances career prospects, demonstrates expertise, and improves understanding. Khoi Vinh describes blogging as an "amplifier."

Practice and Improvement:

Consistent writing and publishing are crucial for improvement. "Writing with stakes" (publicly sharing your work) is the most effective learning method.

Finding Your Voice:

Start by simply sharing your knowledge. Enhance your writing by incorporating personal experiences, quoting others, and conducting research.

Guest Posting:

If pitching to a site, carefully review their guidelines.

Useful Tools:

Dropbox Paper for collaboration and Grammarly for proofreading are suggested tools.

The above is the detailed content of Advice for Technical Writing. For more information, please follow other related articles on the PHP Chinese website!