The [[Coding and writing are converging|convergence of code and writing]] has implications on the career trajectories of both coders and writers, as well as the tech industry as a whole. ### For coders #### [[Expressive code]] is essential ![[assets/expressive-code.png]] [^betterprogramming] This meme pokes fun at the fact that actual programming takes up a surprisingly small slice of a coder's pie of work. While this is a bit of an intentionally exaggerated example, I think it has an element of truth in it, and the truth is that it's becoming way more important that your code be understandable by others than that you make it work in the first place. If you're the only one who can understand what you've done, then it can only be a short-term success -- it lasts as long as you stay on this project. Then all bets are off. As coders, we can pay more attention to yes, the way variables are named, but also the comments we leave within our code, not mixing levels of abstraction, and keeping functions atomic. This is why peer reviews are so important: if you give your code to someone else and they can't follow your train of thought, there's a problem. It might not be a problem you have to solve now, but it's one that someone will have to, at some point. #### Documentation is part of development ![[assets/k6-docs.png]] [^k6] Many things can't be explained by comments within the code, so comments need to be accompanied by a more detailed explanation. The company I work for maintains an open-source load testing tool, and our developers are great at taking responsibility for explaining their own work. At k6, writing documentation is part of a release. Developers write documentation for every new feature they build. They also answer questions in our public community forum. They just treat it as part of their job - because it is. Part of the job of a coder will be to describe what you've done, and why. Communication will become a more crucial skill in developers. Developers will need to learn how to write changelogs, release notes, readmes for repos, and contribution guidelines. It's YOUR work, after all. Be proud of it. #### Writing as a development skill [[Writing]] and [[Technical Writing]] will become cornerstones on which to hire developers, who need to improve these skills to remain competitive. ### For writers #### Use of development tools for writing Technical writing and documentation is being treated more and more like code is. [^modern] They will be kept in Git or other version-controlled repositories, in lightweight [[Markup languages]] like [[obsidian-playbook/Using Obsidian/02 Making Notes in Obsidian/Markdown]] and [[LaTeX]], and published on statically generated websites like [[Hugo]]. Once stored along with application code, documentation could be seen more as "documentation code" rather than writing. #### Refactoring in writing [[Refactoring code|Refactoring]] is a well-known concept in programming. Programmers rarely believe they have to get it right the first time, but for some reason, writers do. Treating written work like a digital garden that is constantly growing and refactoring it like code is a healthier and more sustainable approach. Getting into the habit of updating blog posts and thinking of writing as a perpetual work in progress rather than a once-off project with a clear end are going to be more important in the future than getting something "published". This transient nature may also change the nature of publishing. ### For both #### Tools that enable both coding and writing become more valuable. - Text editors should be able to function as [[IDE]]s and as document editors - Tools like [[Obsidian]] and [[Roam Research]] allow prose and code in the same page - A word document will be the same as a program. - I already spend most of my time creating articles in [[obsidian-playbook/Using Obsidian/02 Making Notes in Obsidian/Markdown]] files. - Challenge: most document editors can't run code, but most IDEs can accept prose. #### Coding and writing skills become equally essential for knowledge workers - [[Writing does not help us learn - it IS how we learn.]] - [[Learning in public]] and demonstrable knowledge increases in value. - [[Prefer visible work]]: A database of what you know, in both code and prose, is a way to increase career capital. #### Clear, systematic, logical thought is the goal. - What is the intersection between coding and writing? What's the thing that coding and writing are converging __into__? It's expressing thought. - The real winner is anyone who can express thought, including intent and instructions, as cogently as possible with words. #### Pay more attention to inclusive language. - Linguistic privilege is inherent in code ("Coding is for everyone - as long as you speak English") -  - Source: [Wired](https://www.wired.com/story/coding-is-for-everyoneas-long-as-you-speak-english/) [^betterprogramming]: devDeejay. (2019). _Expressive clean code: Tell beautiful stories with beautiful programs_. Better Programming. Retrieved from https://betterprogramming.pub/clean-code-give-meaning-to-your-code-to-exist-f966b3f00848 [^k6]: _k6 docs_. k6.io. Retrieved in June 2021 from https://k6.io/docs [^modern]: Etter, A. (2016). _Modern technical writing: An introduction to software documentation_. Retrieved from https://www.amazon.com/Modern-Technical-Writing-Introduction-Documentation-ebook/dp/B01A2QL9SS/