Artificial Intelligence: Polishing
I'm off to Disney World, but I've prepped insights on using AI for polishing your coding and writing to finish up our May topic!
Phew, what a week! Actually, I'm lying, I'm going on vacation the week of the 19th (to Disney world!) and am scheduling this email an extra week in advance. I'm sure it was a fun week, though! Or maybe incredibly stressful bringing a 4-year-old and 1-year-old twins to Disney world... I'll let you know!
Highlights
Things I've been doing on the internet
Here's some of the things that I'm scheduling in advance to go out this week while I'm hanging out in Florida! I sure hope all these links work!
- Podcast: Overcommitted Ep. 8 | Technical Debt Prioritization
- Illustration:
Things I've enjoyed on the internet this week
Hopefully nothing, because I've been on vacation! But if you've got something you want me to read and feature in this newsletter, send it to me at brittany@balancedengineer.com!
Onto the content!
This month, we're diving into artificial intelligence and how it can enhance your workflow as a software engineer. We started with a primer on what AI actually is, and now we're exploring specific use cases. First we talked about how I use it in my brainstorming process, then we focused on using AI for debugging. Today, we'll finish out the month with a focus on polishing.
May Theme: Artificial Intelligence
Think of polishing as that final 10% that often makes the biggest difference in how your work is received. It's the difference between code that works and code that's elegant, between writing that communicates and writing that inspires. This is where AI tools can be your secret weapon.
How I Use LLMs for Polishing Writing
Writing is a crucial skill for software engineers, whether it's documentation, messages, or technical proposals. Here's how I use LLM tools to add that final polish:
Improving Technical Documentation
When I've finished drafting documentation, I use this prompt:
Review this technical documentation for clarity, completeness, and professional tone. Suggest improvements that would make it more useful for [target audience]:
[Paste your documentation here]
Specifically look for:
1. Places where more context or examples would help
2. Technical terms that need better explanation
3. Areas where the structure could be improved
4. Any inconsistencies in style or terminology
The LLM tools often catches places where I've assumed knowledge that a new team member wouldn't have, or where I've skipped steps that seem obvious to me but wouldn't be to everyone.
Enhancing Proposals and Reports
For important documents like architecture proposals or epic reports:
I've written this [proposal/report] about [topic] for [audience]. My goal is to [convince them to adopt a new architecture/summarize our team's achievements].
[Paste your document]
Please suggest improvements that would:
1. Make my key points more compelling
2. Strengthen the overall narrative
3. Address potential objections or questions
4. Ensure the language is professional but engaging.
This has helped me transform dry technical documents into persuasive narratives that actually get read and acted upon. It also helps me keep this type of writing focused on the key point of what I'm trying to communicate.
Refining Slack Communication
For crucial slack messages where the stakes are high:
I'm sending this message to [audience] regarding [subject]. I want to come across as [professional/collaborative/firm but respectful].
[Paste your message]
Please suggest improvements that would:
1. Make my message clearer and more concise
2. Ensure the tone matches my intention
3. Identify any potentially confusing or ambiguous statements
4. Help me get the response I'm looking for
I don't do this often, but I've found this particularly helpful for those delicate messages discussing project delays or requesting something from other teams.
How I Use LLMs for Polishing Development Tasks
While writing this newsletter, I realized I don't use AI for polishing code as much as I could! So I experimented with some new approaches that I'm excited to share with you:
Code Readability and Style
For making code more maintainable:
Review this [language] code for readability and adherence to best practices:
[Paste your code]
Please suggest improvements that would:
1. Make it more maintainable for future developers
2. Better follow standard conventions for [language/framework]
3. Improve variable/function naming for clarity
4. Simplify complex sections while preserving functionality
This seems helpful for catching embarrassing inconsistencies in naming conventions and identify places where I was being unnecessarily clever instead of clear.
Documentation and Comments
For improving inline documentation:
Review the comments and documentation in this code:
[Paste your code with comments]
Suggest improvements that would:
1. Clarify the purpose of complex functions
2. Explain "why" decisions were made, not just "what" the code does
3. Identify areas where additional comments would help future developers
4. Ensure comments stay updated with the code
The last point seems especially helpful, because I often forget to update comments as I update code.
Refactoring for Performance and Elegance
When I want to polish code beyond just "working":
I'd like to refactor this [language] code to be more elegant and performant:
[Paste your code]
Please suggest improvements that would: 1. Reduce redundancy without sacrificing readability 2. Optimize for performance where reasonable 3. Make better use of language/framework features 4. Structure the code more logically
This seems useful for discovering more elegant patterns and language features I wasn't utilizing fully.
The Difference Between Debugging and Polishing
While debugging focuses on fixing what's broken, polishing improves what already works. I've found that AI excels at this because:
- It can evaluate your work against patterns and best practices it's seen across thousands of examples
- It brings a fresh perspective without the emotional attachment we have to our own work
- It can suggest multiple alternative approaches for you to consider
Tips for Effective AI Polishing
Through my experiments, I've found these approaches most helpful:
- Be specific about your audience and goals - "Make this better" gets generic suggestions; "Make this more understandable for junior developers" gets targeted improvements.
- Ask for multiple alternatives - Sometimes seeing several options helps you find the perfect approach or combine ideas.
- Use AI for the final review, not just the initial polish - After you've made improvements, run it by the AI again with a fresh prompt to catch anything you missed.
- Focus on one aspect at a time - Asking for improvements to performance, readability, and documentation all at once often results in mediocre suggestions for all three. Iterate!
- Remember that you're the expert - AI can suggest, but you decide what actually makes your code or writing better for your specific context.
Have comments or questions about this newsletter? Or just want to be internet friends? Send me an email at brittany@balancedengineer.com or reach out on Bluesky or LinkedIn.