Writing for Developers - A must-read for becoming a developer who can write!

With artificial intelligence helping developers, it's not enough to just write good code. Documentation, technical blogging, crafting user-friendly messaging, and more. Writing skillsis now an essential skill of a good developer.

Kim's book is a practical guide to help developers get more value from their writing in the face of these changes. In this post, we'll summarize the key takeaways from each chapter and discuss why this book is a must-read for developers.

"Writing for Developers book overview

• Author: Cheoljoo Kim
• Publishers: non-private
• Year of publication: 2019
• Target audienceDevelopers, planners, IT workers, and anyone else who needs to write well.
• Features:
  • From in-code writing (variable names, comments) to out-of-code writing (technical blogs, proposals, etc.).
  • Practical, hands-on examples and guidance.
  • A clear and practical writing methodology from a developer's perspective.

Key messages

1. The importance of writing

- Developers' writing is an essential skill that goes beyond code to enhance collaboration, communication, and problem-solving.

2. Balancing code and documentation

- Clear documentation is just as important as well-written code. Documentation makes projects more productive and maintainable.

3. Write clearly and concisely

- Writing with the reader in mind will make your technical content more effective.

4. Immediate practical application

- The principles and methodologies in this book are concrete and practical so that you can put them to work right away.

Chapter 1: Writing basics developers need to know

The first chapter of Writing for Developers covers the basic philosophy and structure of writing.

1. accuracy, brevity, and readability

• The key is to create a structure that conveys the right information, cuts through the clutter, and is easy to read.
• Consider your reader's perspective, prioritize, and concisely convey the key messages of your post.

2. Structure your sentences

• The Pyramid structureis recommended.
• Putting important content up front makes it easy for busy readers to grasp key information.

3. select a format

• Descriptive, modified, schematic, and more Choose a writing format that fits the context.
• For example, release notes work well in paraphrase, while technical blogs work well in narrative.

Chapter 2: Naming and commenting to reduce development time

Good naming and annotation facilitates communication between team members and makes maintenance easier.

1. naming convention

• Variable and function names should be intuitive and consistent across your team.
• Example: totalVisitors is easier to search and understand than visitorCount.

2. How to write an annotation

• Write only when necessary: Well-written code should act as a comment in and of itself.
• Describe the context: Write why this code is needed and what the intent was.

Example

• Bad example: // Add one to the count.
• Example: // Increase the number of users by 1 to reflect an inventory adjustment.

Chapter 3: Write error messages that communicate with users

User-friendly error messages not only help with troubleshooting, but also greatly improve the user experience.

1. Principles for writing error messages

• Description: A clear description of the problem and the cause of the error.
• Workaround: Provide a solution that the user can follow.

2. bad and good examples

• Bad example: Invalid input.
• Good example: The value you entered is invalid, please enter your name in Korean only.

3. the fluctuating button message

• Bad buttons: Yes / No
• Good buttons: Save and leave / Leave without saving

Chapter 4: Writing Release Documentation and Crash Reports from the Reader's Perspective

Release documentation and crash reports are important documents that build trust between you and your company.

1. How to create a change log

• Categorize items from a user perspective: divide them into new features, enhancements, and bug fixes, or group them according to user flow (start-middle-end).
• Be concise and clear by removing unnecessary details.

2. summarize and synthesize

• Summarize with a paraphrase to improve readability and emphasize key messages.
• Example: Getting into the game room faster.

3. Troubleshooting-focused reports

• Write in the following order: problem, cause, solution, and follow-up plan.
• Help readers easily understand the current state.

Chapter 5: Writing development guides with description, illustration, argument, and narrative

Development guides should make good use of explanations and arguments to make it easy for the reader to understand.

1. description

• Clearly describe the scope, purpose, and features of the service.
• Example: Category in AWS: "Cloud Storage Services"

2. describe

• Complex structures are explained using a combination of illustrations and text.
• Text-to-picture match: Visuals and text should match to avoid confusion.

3. arguments

• Back up your claims with concrete evidence to convince your readers.
• Example: "Test that there is no performance difference when increasing the value to 30."

Chapter 6: Write an SI proposal that wins you business

Your SI proposal is an important document that represents your company's competitive position.

1. Create a structured proposal

• Define the problem: Clearly identify the customer's needs and problems.
• Solution: The value our solution will deliver and a specific action plan.

2. Play to your strengths

• Highlight the strengths that differentiate you from your competitors.
• Example: "Our service guarantees 20% faster processing speeds."

Chapter 7: Writing and running a tech blog made easy

A tech blog is a great tool for building your personal brand and contributing to your community.

1. authoring tips

• Write from your perspective, based on your experience and data.
• Consider your reader's level, but stay true to your own originality.

2. operational tips

• Post regularly to build trust.
• It's even better if you include a simple snippet of code or the results of an experiment.

Finalizing a developer's written review

"Writing for Developers provides a practical guide to writing that every developer needs to know. If you want to become a developer who adds value with your writing, not just a developer who codes well, this book is a must-read. It will take both your development and your writing to the next level!

#Developer's Writing Book Appearances Glossary of Terms

1. click Release Note

• Definition: Release notes are documents that document the features added, errors fixed, and improvements made when a new version of the software is released.
• Purpose: Used to notify users and stakeholders of software changes.
• Components:
  • What's new: Major new features added to the software.
  • Fixed errors: Bugs or issues from previous versions that have been resolved.
  • Enhancements: Improvements to the software, such as performance, UI/UX, and stability.
• Example:
  • [Version 1.2.3]
  • New: Added dark mode.
  • Improvement: Improved page loading speed 20%.
  • Error fix: Corrected error message to display correctly when login fails.

2. Change Log

• Definition: A change log is a document that records the history of changes in software. You can think of it as the internal history on which release notes are based.
• Difference (compared to release notes): Release notes are intended for external audiences, while change logs are written for developers or internal teams.
• The change log is more detailed and technical.
• Use: To facilitate communication between developers and to track revision history.

3. SI proposal

• Definition: A system integration (SI) proposal is a document created to win a system integration project.
• Purpose: Analyze customer problems and propose technical and operational solutions to solve them.
  • Components:
  • Project overview: Your needs and goals.
  • Technical solution: The technology and system structure you propose.
  • Expected outcome: The expected outcome after the project is completed.
• Importance: Very important because the quality of your proposal will determine whether or not you get the project.

4. Naming Convention

• Definition: A convention for systematically naming variables, functions, classes, etc. within code.
• Major conventions:
  • Camel case notation (Camel Case): The first word is lowercase, and the first letter of subsequent words is capitalized.
    • For example: totalVisitors, calculateSum.
  • Pascal notation (Pascal Case): Capitalizing the first letter of every word.
    • Example: CalculateSum, TotalVisitors.
  • Snake notation (Snake Case): Write all words in lowercase, and use an underscore _ between words.
    • For example: total_visitors, calculate_sum.

5. click Comment

• Definition: A comment is text within your code that describes the purpose or behavior of a particular piece of code.
• Type:
  • Line comment: A single line comment. Usually starts with // or #.
    • // Initialize user input values.
    • input = "";
  • Block comments: Multi-line comments. Written as /* */ or """ """
    • /*
    • This function serves to store user data.
    • Storage format: JSON
    • */
• Role: To make code more understandable and maintainable.

6. technical blog

• Definition: A blog written by developers to share their experiences, skills, and know-how.
• Objective:
  • Personal branding: Make yourself known technically and expand your network.
  • Community contributions: Contributing to the developer community by sharing useful information.
• Writing tip: Be specific, centered on experience and data. Include code snippets and visuals to increase readability.

7. user-friendly error messages

• Definition: A message that helps users understand and solve a problem.
• element:
  • Error Description: Clarify what the problem is.
  • Cause: Why the error occurred.
  • Workaround: Specific instructions for the user to resolve the error.
• Bad and good examples:
  • Bad example: Error 404
  • Good example: Page not found, please double-check the URL.

In addition to articles by developers, we have book recommendations for developers. Developer book recommendations - 'Soft skills', must-reads for the perfect blend of development and life! Check out the post to see what we're talking about! We've got a book written by a developer to help you dive deeper into the world of developers.