Technical skill and content creation are equally important for your software development or (software development adjacent) career. Technical skills such as coding help you to perform the job at a base level, but content creation can solidify you as a leader in the industry. I acknowledge that not everyone has the privilege of creating content alongside completing their daily job duties and personal responsibilities, but it is a worthy investment. Creating technical content can make it easier to land jobs, get promoted, and influence the direction of our industry because it enables hiring managers and other tech leaders to take a peek into your brain and your thought process. More importantly, it helps you absorb and solidify concepts that you’ve learned. You can be the smartest, most skilled software developer in the world, but if no one knows who you are, then your opportunities may be limited. Content creation helps you advocate for yourself. It might seem cringe, but you can put yourself out there in a non-cringey authentic way. Folks like Kelsey Hightower established and advanced their careers by sharing their thoughts in an authentic and thoughtful way.
My favorite form of technical content creation is blogging. Thanks to my mom, I developed a passion for reading and writing at an early age, so writing has always been my preferred method of self-expression. I had an endless supply of picture books, cassette-tape audio books, novels, poetry, and half-filled notebooks documenting my childhood experiences. When there was no heat in my house, my mom would bring my siblings and me to the library, so the library became my second home. Disclaimer: I’m not a perfect writer; it’s just something I enjoy doing.
Unfortunately, I abandoned writing in early adulthood because I learned that it’s hard to make money as a writer, and I had one goal in mind: make LOADS of money. I grew up poor, and I was determined to improve my quality of life, so I focused all my energy on a career that makes money: software development.
Years later, I started my third full-time software development job, and my manager Andy Cunningham encouraged me to write what I learned on the job. As part of my sprint, I’d fix a bug or implement a new feature, and then I would write about it. One of my first technical blog posts was about how I used GitHub Actions to sync our repository with our AWS S3 Buckets. Months later, I landed my current role as a Developer Advocate, and part of my role is to blog.
While I was excited to combine my childhood skill (writing) with the skill I learned in adulthood (coding), I was also intimidated. Writing about technology didn’t seem as easy as writing a poem or an essay. With poetry, I had all creative authority, and with essays, teachers gave us guidelines. But, what was a technical blog post supposed to look like? I worried and struggled with the following concepts:
A common reason that technologists don’t write is because they’re scared.
If you’re scared that you don’t have anything new or different to write about…
Remind yourself that you don’t have to write about anything revolutionary or inventive, write what you know. While someone may have already written about a similar topic, they won’t explain it the same way you will. And the way you explain and describe information will reach a particular audience that learns and consumes information the same way you do.
If you’re scared that your writing skills aren’t up to par…
Remind yourself that this is your platform to practice. You will improve over time, and sometimes blog posts don’t need to have flowery vocabulary and complex sentences. Sometimes, the simpler a blog is written, the easier it is for the audience to consume.
If you’re scared that you don’t know enough…
Perhaps, you only know HTML, but you know more than someone who doesn’t know HTML. You will continue to grow and learn over time. You don’t need to wait until you get to a certain point because as technologists, we’re always learning. There will always be something that we don’t know.
If you’re scared of making mistakes…
Embrace your mistakes; they help you grow. I make mistakes all the time. Sometimes, I have grammatical errors in my blog posts or even technical errors, and someone corrects me. I learn from those mistakes and I’ve become a better writer, educator, and engineer as a result. Don’t aim to make mistakes, but when you do, know that everyone makes mistakes and it’s part of our journey to greatness.
If you’re scared that you don’t have time…
This is totally fair as we all have varying responsibilities and limited time. However, it is a worthy investment to reflect on what you’ve learned and share your knowledge with the world. If possible, work with your manager to carve out regularly scheduled time to write, and your blog posts don’t have to be long. They can be as short or as long as you want. You have creative authority over your content.
If you’re scared of criticism…
Remind yourself that you are writing for you. You are writing, so that you can look back and reflect on your growth. You are writing, so that you won’t have to repeatedly Google or ask your coworkers for help on the same questions. The harmful opinions of others don’t matter. You can always delete their comments or respectfully respond and continue to live life. I’ve found that people like to critique others when they feel threatened.
As you write code at your job, complete side projects, or contribute to open source projects, keep a running list of things you’ve learned.
I keep a list in my Notes app on my Mac computer and iPhone. It looks like this
### Idea list
Hack.Diversity
- How to negotiate salary
- Write thank you letters after interviews
- How to pass the technical interview
- How to learn / navigate a new codebase quickly
- Tips for passing the CompTIA+ test
- Code
- Invite Automation
- Teaching to Empower: Supporting Early Career Devs
- Generate Social Cards with JavaScript
- From Code to Cloud — Git Emoji
- Build a Blockchain Simulation with JavaScript
- Make better pull requests
- Fuzzy Search Made Easy
- Overcoming the Fear of Contributing to Open Source
- How to Convince Your Boss to Open Source a Project
- Create the Perfect ReadME for your Open Source Project
Small things I learned with code
- Linked issues
- Fusejs
- How to make a pull request template
- .github/.github/PULL_REQUEST_TEMPLATE.md
- https://github.com/open-sauced/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md
- .github
- Issue templates
- Forms yaml
- Being autonomous
- Turning a Checkbox into a circle
- Handling routing with netlify
- Dependencies vs devDependencies
- React functions run on load or after
- Dealing with broken images in React
- SEQA
- Rendering components
- Using classList
- Invite automation
- Automatically generate a social image card
- Pull request template forms
GitHub ideas
- Prompt engineering tips with GitHub Copilot
- Lowering barriers with GitHub Codespaces
- Automatically install extensions with GitHub Codespaces
- Automatically install npm dependencies with GitHub Codespaces
- Automatically run your node app with GitHub Codespaces
- GitHub Actions extension
- Using GitHub Pages to federate your Mastodon identity
- Building a to do list user interface with GitHub Copilot
- Sending a toot with GitHub Copilot
- P5.js with GitHub Copilot
- I made a GitHub action with my voice
- I used AI to build AI
- How does GitHub Copilot help businesses
As you can see, my ideas range from simple concepts like "Converting a checkbox into a circle with CSS" to more advanced and creative concepts (like "Building a GitHub Action with my voice"). Some of the ideas are also repeated. Whenever I get an idea or one of my managers mentions that I should cover a topic, I write it down.
Keeping a list of ideas is helpful, so that when you want to write, you’re not also wasting energy and time, brainstorming topics.
It’s worth noting that I haven’t written about many of the topics listed above. I only write about what I’m most passionate about at the moment or most needed at my job (because this is my job). If it’s one of the ideas on the list, then I will write about it. However, if I have a random spark of inspiration, I will act on the idea immediately. On the other hand, I may also have to write about a topic requested by my coworkers, and I’ll focus on that. I choose the most urgent or the most exciting topic because that helps motivate me.
Also, consider granularity in your topics. If you want to write about a general topic, such as React, it would be difficult to write about every single concept of React. It would take a book or documentation to cover the entire framework. Instead, I suggest creating a general overview of React or picking a very subtopic such as, “Understanding the useEffect Hook” or “How I used React to build a blog”
Before writing anything, I always read. Reading inspires my:
Now that you know what you want to write about, and you’re inspired to write, it’s time to determine who you are writing for.
As humans, we have a tendency to want to write for everyone. We want to teach and help everyone, and that’s not wrong, but I wouldn’t suggest doing this for a blog post. I often talk with people who have goals around content creation, and they want to target junior engineers, mid-level engineers, and senior engineers simultaneously. If you try to reach everybody, you might end up creating a really long blog post that no one wants to read or you might overwhelm yourself and never actually finish the blog post. Trust me; it’s happened to me before and other technical writers. Even if I do finish it, the blog post ends up having every low engagement and it looks messy.
If you choose a very specific audience, then the other audiences will still benefit. For example, I’ve written blog posts for beginners, but sometimes senior engineers let me know that they still learned something new from the blog post or that they appreciated the way I broke down fundamentals.
The person I usually pick to write for is me, specifically past me. Here are examples:
Now, it’s time to plan what you write. Building an outline helps to align your thoughts in a way that readers will understand. Feel free to tweak the outline templates below, but this is what I use to write my own blog posts
If I’m writing a blog post guiding people step-by-step on how to do accomplish a task, I will use an outline like the one below:
Intro
- Hook
- Problem statement/What this solves for myself or readers
Step-by-Step Guide
1. Step 1
Optional: brief explanation of the step with supporting links for folks to learn more
2. Step 2
Optional: brief explanation of the step with supporting links for folks to learn more
3. Step 3
...
N. Final Step
Conclusion
- Recap of the process
- Final thoughts or additional tips
- Call to action (e.g., encourage readers to try the steps and share their results/feedback)
Check out an example that follows this outline: How to send a tweet with GitHub Copilot
I define an explainer blog post as a blog post that explains a topic, but it doesn’t necessarily walk people through accomplishing a task. The main purpose is for readers to get an introduction to a concept.
Intro
- Hook
- Brief overview of the topic and why care
Body
1. Key Concept 1
- Definition/explanation
- Examples
- Importance or relevance
2. Key Concept 2
- Definition/explanation
- Examples
- Importance or relevance
3. Key Concept 3
- Definition/explanation
- Examples
- Importance or relevance
...
N. Final Key Concept
- Definition/explanation
- Examples
- Importance or relevance
Conclusion
- Summary of the key concepts
- Closing thoughts or implications
- Call to action (e.g., encourage readers to explore further or ask questions)
Here’s an example of a blog post that follows this outline: Why are people developing in containers?
These types of posts are posts where I just share my opinion on the direction that industry is going. Many times, I use it to create productive conversation and share my leadership skills.
Intro
- Hook
- Brief introduction to the topic/opinion and why it matters to me
Body
1. Supporting Point 1
- Explanation of the point
- Supporting evidence or examples
2. Supporting Point 2
- Explanation of the point
- Supporting evidence or examples
3. Supporting Point 3
- Explanation of the point
- Supporting evidence or examples
...
N. Final Supporting Point
- Explanation of the point
- Supporting evidence or examples
Counter arguments (optional)
- Address potential counterarguments or opposing views
Conclusion
- Reinforce the opinion and provide a call to action
Here’s an example of a blog post that follows this outline: The Hard Parts of Developer Advocacy for me
These are posts that are often written in list format. The reason they’re written this way is to make the concept fun, quick and easy to consume for readers. These types of blog posts are often have titles to the ones below:
Here’s an example of a blog post that follows this outline: 8 things you didn’t know you could do with GitHub Copilot
This is an odd suggestion, but I do my best thinking in the shower. I think the sound of running water helps me to focus on my thoughts. In the shower, I can write a whole blog post in my mind. Besides taking a shower, you can try other activities that can stimulate your mind:
Disable all distractions and start writing. I strongly recommend that you don’t edit as you write. I find that disruptive for my flow. I fill out each part of the outline that I created in whatever order that I prefer. I write the way I speak, and I just keep going. After I’ve written all my thoughts on paper, I will start editing.
My editing process consists of deleting irrelevant paragraphs, fixing spelling mistakes, and removing unnecessary punctuation marks. I’m a super light editor. I feel that if I edit it too much or spend too much time perfecting my blog posts, then I will never press publish. In the following paragraphs, I expand a bit more on my editing process. However, the way I look at it is, I want to get my thoughts out there. Once I do, someone will reach out to me – like my job and ask for a more refined version of my blog posts. Then, I could use resources my job provides me like professional editors to improve my blog posts.
Also, I recognize that it doesn’t matter how much I edit; my blog post will always need more editing. It’s like code – there’s a bug somewhere. Sometimes, I just edit it after I publish. Often, people message me to say that I spelled a word wrong, and I usually update it afterwards.
It’s no big deal. Write for completion rather than perfection.
There are some people who find writing difficult, and that’s okay. Brian Douglas told me about a tip that could help folks who struggle with putting words on a paper: speak. Record yourself speaking, upload the audio to your computer, and use a tool that can transcribe those words.
The tool I suggest is Descript. It does a great job of transcribing audio. It may have a few mistakes here and there, so double check what it generates and make small edits.
Reading my writing aloud enhances the quality of my content. When I read text I wrote in my head, I may notice particular issues, but reading aloud allows me to:
Digital writing assistants like Grammarly find errors you might have missed. Word Tune is another tool that I find helpful. It’s great because it takes my hard-to-understand sentences and converts them into clear, terse sentences. ChatGPT is another tool, but this one is a little more controversial. While I don’t encourage folks to use it to write whole articles, it does give great feedback. I’ll often prompt ChatGPT with the following: