John Crickett’s Post

The best software engineers write clearly. Clear writing has no missing or extra words, no ambiguous statements. It's very hard to show this without examples and counter examples. And even then, it's often extremely contextual if the writing is clear or not. Clear writing for an ad is likely not clear tech specs. Fortunately, there's a clear path to getting better. Write and share your writing with others. They'll let you know when it's unclear.

Very well said. Identify the problem first. Make sure you understand what the problem is - ideally prove it with red test if it is a bug. Think about the solution, make a plan. Prepare general behavior test cases. If this is something new - discuss it with the team. Code. Code the test first, it will help you identify the code design flaws early. Just like any other craft - don’t cut before you measure.

Good advice

If you're writing code daily, remember: 1. Don't over-engineer the solution 2. Solve the problem first, then clean things up 3. Ask for feedback from your team Writing code is complicated. Keep the process simple.

Writing is an essential skill for software engineers but is often underrated. The more you move on in your career, the more you spend time writing words rather than code. Clear writing helps you get your ideas across quickly, reduces misunderstandings, and puts you and others on the same page. Also, writing lets you share your expertise with the tech community. This not only helps others but also builds up your reputation. However, becoming a better writer takes consistent practice, learning, and refinement. There are three steps to writing a good piece of content: the first draft, editing, and getting feedback. I wrote more about each of them in the latest issue of the Polymathic Engineer. Read it here: https://lnkd.in/eyh3_32i

As an aspiring writer, I often wondered: what can software engineers learn from great writers? Inspired by Stephen King's "On Writing," I realized there's much more to it than I thought! Join me in exploring these insights in my new article

As a technical writer in software engineering, your words carry weight only when backed by knowledge. You can’t document a process you don’t fully grasp or create guides without hands-on experience. Dig into the code, understand the tech, and your writing will shine with clarity and authority.

A few weeks ago, my new Local Programs chief encouraged me to look into professional development in technical writing/documentation. I've been in the space since my days at Badgerland Girl Scouts, when I wrote tip sheets for volunteers teaching coding concepts to Daisy and Brownie scouts. Could I learn something new? You betcha! Google's Technical Writing Courses are AMAZING! Initially designed for Google engineers writing software development documentation, the skills taught in their courses are easy to apply to most applications of technical writing. As I put the finishing touches on our manual for non-traditional locally let transportation projects, I'm applying concepts I learned in Technical Writing One. #technicalwriting #technicaldocumentation #professionaldevelopment #googletechnicalwriting Google for Developers https://lnkd.in/dfhHd8Ud

Do you need help learning how to write technical documents? I'll be facilitating Technical Writing II for Google on Wed. Aug. 28, 2024 @ 1PM Eastern with Jeremy Pugh. More info at https://lnkd.in/dmJRxQYB The objective of Technical Writing II is to help improve the writing of Engineers and Developers through focused individual and group exercises. By the end of the course, you'll know how to: Organize large documents. Edit documents. Illustrate technical concepts. Create conceptual documents and tutorials. Create useful sample code and code comments. Describe anything. #KAM