Talks
Speakers
Events
Topics
Sign in
Home
Talks
Speakers
Events
Topics
Leaderboard
Use
Analytics
Sign in
Suggest modification to this talk
Title
Description
As a developer, you're asked to write an awful lot: commit messages, code review, achitecture docs, pull request write-ups, and more. When you write, you have the power to teach and inspire your teammates—the reader—or leave them confused. Like refactoring, it's a skill that can elevate you as a developer but it is often ignored. In this session, we'll use advice from fiction authors, book editors, and technical writers to take a pull request write-up from unhelpful to great. Along the way, you'll learn practical tips to make your code, ideas, and work more clear others.
Date
Summarized using AI?
If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.
Show "Summarized using AI" badge on summary page
Summary
Markdown supported
In his talk "Refactoring: A Developer's Guide to Writing Well," presented at RailsConf 2021, Jordan Raine addresses the crucial yet often overlooked skill of writing in software development. He emphasizes how effective writing can enhance communication among team members and improve clarity in technical documentation such as pull request write-ups, commit messages, and code reviews. The session draws parallels between the writing processes in fiction and technical domains, suggesting that developers can greatly benefit from refining their writing skills. ### Key Points: - **Importance of Writing**: Writing is an essential skill for developers, as communication often becomes more critical than technical ability as careers progress. Clear writing helps convey ideas effectively to various audiences, including non-technical stakeholders. - **The Writing Disconnect**: Despite the extensive writing developers do throughout their careers, many do not become proficient writers due to a lack of deliberate practice and feedback. - **Pull Request Write-Ups**: Pull requests demand clear explanations of code changes. Poor write-ups can lead to confusion and slow down the review process. Common deficiencies include: - **Nothing Write-Ups**: Offer little to no information. - **Cluttered Write-Ups**: Provide excessive details that dilute useful information. - **Noisy Write-Ups**: Overloaded with irrelevant information, making it hard to extract what matters. - **Strategies for Improvement**: - **Assume Knowledge Gaps**: Always consider that the reader knows less about the topic than assumed. - **Use Concrete Examples**: Translate abstract concepts into specific, relatable terms to aid understanding. - **Walk Through Processes**: Describe processes step-by-step, helping readers follow the thought process behind code changes. - **Refactoring Writing**: Much like code, writing comes from iterative improvements. The first draft can be a rough version, and through edits, conciseness and clarity emerge. Techniques include: - **Cutting Unnecessary Words**: Streamline content by removing redundant or irrelevant phrases. - **Avoiding Ambiguities**: Anything that confuses the reader should be clarified or removed. - **Using Active Voice**: Utilizing active rather than passive voice enhances readability and engagement. - **Presentation**: Utilize headings, screenshots, and links to make documentation more informative and easier to digest. A engaging title is also crucial as it sets the stage for the reader. The session ultimately encourages developers to approach their writing with the same discipline as coding, suggesting that refining writing skills is a continuous journey. By treating written communication as a draft that needs regular review and improvement, attendees are urged to become proficient in their writing, which in turn adds value to their technical contributions. For further exploration of the techniques discussed, Raine directs viewers to resources like refactoringwords.com and recommends diving into literature on effective writing.
Suggest modifications
Cancel
