DEV Community: Maddy

My First Year As a Technical Writer

Maddy — Wed, 10 Apr 2024 09:08:44 +0000

In April 2023, I quit software engineering and accepted an offer to join Cloudflare as a technical writer on its Developer Platform. Before that offer, I had been a software engineer (Java developer) since about 2019.

My first year as a technical writer taught me a lot about technical writing, and I feel that my interpersonal skills have grown significantly in the past 12 months.

Work-life balance

Work-life balance is subjective because it depends on the company and, more specifically, the team. My work-life balance as a technical writer is the best I've ever had.

When I was a software engineer, I found it difficult to switch off from work completely.

I was concerned about things breaking, finding a solution to a bug, not being able to complete tasks within tight deadlines, impressing my manager, and so on.

As a technical writer, I still have deadlines and tasks to complete by a certain date, but overall, deadlines have been more relaxed.

I can switch off from work, I'm not concerned about things breaking, and there's no "urgency" because content is not mission-critical.

Blogging is different from technical writing

In my first 3-6 months, I learned how to write as a technical writer. Before becoming a professional technical writer, I've been writing on this blog since 2021.

Blogging helped me a lot with my current role, but I still had to learn about:

Technical communication
Information Architecture
Markdown
User journey
Docs-as-code

In addition to the topics above, I've also had to learn about the company's and the team's processes. This has been a huge learning curve, but having the right manager and supportive colleagues has made the learning enjoyable and not overwhelming.

Technical writing is more sterile and straight-to-the-point than blogging. I had to learn to cut out the fluff and tell the user what they needed to do to use the product without adding words that carry no value.

You have to advocate for yourself

As a technical writer, you'll often have to advocate for yourself. Technical writing is an underrated and taken-for-granted role.

Sometimes, software documentation is not considered part of a successful product but is more like a side-project ("after-thought").

As a technical writer, you must speak up often, advocate for your work, proactively engage with the SMEs (subject matter experts), and participate in all the meetings necessary to perform your role successfully.

Technical writing is about asking the right questions

Technical writers are responsible for identifying the information the users need to use a product successfully, and create content from there.

Since software engineers are responsible for building the product, technical writers must ask questions to access the knowledge they need to write the documentation.

Software engineers build the product, but they don't know (or take for granted) what the users need to use the product from scratch.

Project management

When I started my role, I was surprised by how project management plays an integral part in my role to ensure that I track my work. I use JIRA on a day-to-day basis to:

Create tickets.
Track how many tickets I close per Sprint.
Track the progress of each product's documentation.

Commonalities between software engineering and technical writing

Both software engineers and technical writers:

Use Git (or other version control) and GitHub.
Use an IDE.
Follow an Agile process.
Both build for the users (but from different perspectives).
Perform peer reviews.

Technical writers write little to no coding, and are more concerned with creating user-focused documentation.

Conclusion

After reading this article, you have an idea of what a technical writer does.

If this article is interesting to you, subscribe to my FREE weekly newsletter.

Is Job Hopping In Tech Bad?

Maddy — Mon, 11 Mar 2024 13:25:27 +0000

Job hopping is the pattern of switching jobs quickly, usually under three years. In the tech industry, this pattern has become the norm (at least before all these layoffs started), and it's used as the primary method of boosting your salary and career prospects.

Job hopping used to be taboo, but changing jobs every two to three years has become widely accepted.

There has been a generational shift in the last few years: years ago, employees worked for the same company for decades and wanted to be loyal.

Rather than letting their progress be dictated by a single employer, many workers felt empowered to actively manage their own careers: moving between companies as needed to advance, gain new skills or look for new opportunities.[The case for job hopping]

Over the last few years, though, employees have been rejecting the notion of company loyalty and starting to do what suits them best.

[...]They should be intentional and strategic with each career move, and they need to be prepared to explain those transitions when discussing their job history with future employers.[What Is Job Hopping? (Pros, Cons and Considerations)]

What are the positive aspects of job hopping?

Higher salary

When you stay in the same company for several years, the usual salary increase you can get is 4%. However, when you change jobs, you can receive a significant pay rise of 8%+.

Variety of experience

Changing jobs frequently exposes you to various skills and domains you wouldn't be able to gain if you stayed at the same company for a long time.

Adaptability

Changing jobs frequently may also signal that you can quickly adapt to a new environment and, therefore, impact the company soon.

Career growth

Managers cannot always give you a promotion for reasons outside their control (position not being available, budget not being enough, hierarchy, etc.). Job hopping allows you to get your desired promotion at a different company.

New environment

Job hopping allows you to experience a new environment with new colleagues and managers and perhaps better internal processes.

How can job hopping hurt your career?

Limited professional growth

When you frequently switch jobs, you cannot absorb enough information and experience to be successful in the long run. When you stay in the same company for a reasonable amount of time (3+ years), you learn the company's domain and the business challenges the domain may carry. This knowledge can significantly benefit you in the future.

An employee moving jobs too often can mean they arent in a position long enough to truly learn the role or gain new skills, says Thomas. It can ultimately damage a persons career: it may be challenging to demonstrate to a new employer previous proficiency and achievements.[The case for job hopping]

Weak social connections

Switching jobs too frequently doesn't allow you to build solid connections with your colleagues. This may hurt you if you ever need a referral or endorsement from a colleague in the future. Having a solid network is crucial, especially during these difficult times.

It may look bad on your resume

Even though switching jobs frequently has mainly become accepted, some recruiters and hiring managers may be reluctant to consider someone who displays a pattern of consistently changing jobs on their resume.

Is job hopping in tech bad in the end?

This depends on how you go about job-hopping.

If you intend to job-hop solely to get a salary bump, you'll eventually reach a point where it becomes unsustainable.

However, job hopping strategically can benefit your career when you stay in a job long enough to gain skills and experience you can leverage in your next role.

A balanced approach would be ideal. Staying at a job for less than a year isn't smart, but working for the same company for 10+ years would mean leaving too much money on the table.

The ideal approach would be to have a balance between short and long job experiences.

Subscribe to my FREE weekly newsletter if you enjoyed this article.

How To Generate Tests Using CodiumAI

Maddy — Tue, 23 Jan 2024 09:00:00 +0000

CodiumAI is an IDE extension that allows you to generate test suites.

CodiumAI analyzes the entirety of your code and then suggests tests as you code.

CodiumAI's main vision is to help developers create better code faster.

To use CodiumAI, you will need:

VS Code or JetBrains IDE installed on your laptop.
Go to CodiumAI and download CodiumAI on your laptop.

This tutorial uses Visual Studio Code with Java.

Once you have Visual Studio Code installed on your laptop, on CodiumAI, select the option to download the free version of your Visual Studio Code.

How to use CodiumAI on Visual Studio Code

Create a Java project on your Visual Studio Code called CodiumAI_Project.

Once you have created your project, open it on your Visual Studio Code.

This is what you should see:

Select the CodiumAI icon at the bottom of the left sidebar to use CodiumAI on Visual Studio Code:

At the bottom, select No Context. Selecting No Context allows you to ask a question without context. For example, you can ask CodiumAI to generate a class called Vehicle with brand, colour and purpose_of_use as private fields.

The code generated will initially be written in Python like this:

class Vehicle: def __init__ (self, brand, colour, purpose_of_use): self. __brand = brand self.__ colour = colour self.__purpose_of_use = purpose_of_use # getter methods def get_brand(self): return self.__brand def get_colour(self): return self.__colour def get_purpose_of_use(self): return self.__purpose_of_use # setter methods def set_brand(self, brand): self.__brand = brand def set_colour(self, colour): self.__colour = colour def set_purpose_of_use(self, purpose_of_use): self.__purpose_of_use = purpose_of_use

CodiumAI allows you to translate code from one programming language to another. Since this tutorial uses Java, you can translate the Python-generated code into Java.

Select Continue this chat , and ask CodiumAI to change the code to Java.

public class Vehicle { private String brand; private String colour; private String purposeOfUse; // constructor public Vehicle(String brand, String colour, String purposeOfUse) { this.brand = brand; this.colour = colour; this.purposeOfUse = purposeOfUse; } // getter methods public String getBrand() { return this.brand; } public String getColour() { return this.colour; } public String getPurposeOfUse() { return this.purposeOfUse; } // setter methods public void setBrand(String brand) { this.brand = brand; } public void setColour(String colour) { this.colour = colour; } public void setPurposeOfUse(String purposeOfUse) { this.purposeOfUse = purposeOfUse; }}

With CodiumAI, you can generate a test suite for your desired code. Select Continue this chat , and ask CodiumAI to generate tests for the above class Vehicle.

import org.junit.jupiter.api.Test;import static org.junit.jupiter.api.Assertions.assertEquals;public class VehicleTest { @Test public void testVehicle() { // create an instance of Vehicle Vehicle vehicle = new Vehicle("Toyota", "Red", "Personal"); // test getters assertEquals("Toyota", vehicle.getBrand()); assertEquals("Red", vehicle.getColour()); assertEquals("Personal", vehicle.getPurposeOfUse()); // test setters vehicle.setBrand("Honda"); vehicle.setColour("Blue"); vehicle.setPurposeOfUse("Commercial"); assertEquals("Honda", vehicle.getBrand()); assertEquals("Blue", vehicle.getColour()); assertEquals("Commercial", vehicle.getPurposeOfUse()); }}

CodiumAI features

CodiumAI:

AlphaCodium: a test-based, multi-stage, code-oriented iterative flow that improves the performance of LLMs on code problems.
Supports any language, even though advanced features are available in Python, JavaScript, TypeScript, and Java.
Allows you to spend more time writing core features instead of tests.
Helps you create bug-free software by thoroughly analyzing your code for edge cases.

To start using CodiumAI, refer to the CodiumAI website.

Reviewing 2023: A Year Filled With Experiences

Maddy — Tue, 02 Jan 2024 10:39:08 +0000

2023 has been a year of change and growth. I spent 2023 filling the following buckets:

Career growth.
Lifestyle and wellness.
Travel and exploration.
Community.

Career growth

In April 2023, I quit software engineering and started a new position as a technical writer for Cloudflare's developer platform.

2023 has made me realize that software engineering is not a role that suits me.

For a long time, I believed I could be a software engineer with "enough practice".

The more I worked as a software engineer, the more I realized I wasn't meant to be one. There's a difference between being "a developer" and being a "competent developer".

I often felt disengaged with the type of work, disagreeing with the Agile practices, and not feeling psychologically safe in the environments I was part of.

The companies I joined as a software engineer were not for me, and I wasn't for them either.

I tried being a software engineer three times but said to myself that I wasn't going to try a 4th time if I felt that the situation was not improving.

Earlier this year, I started sending CVs for positions that involved more communication (either written or verbal).

I initially sent a CV for a Solutions Engineer role at Cloudflare but got rejected because I had no experience. I sent another CV for a technical writer role at the same company and got offered a role, which I immediately accepted.

When I told some people that I would switch to technical writing, they answered that I would feel bored because it's repetitive work.

My experience so far has been far from this:

As a technical writer, I get paid to learn.
It's an educating job where I teach users about a product.
It's a role that drives innovation, competitiveness and customer satisfaction.

As a technical writer, I have more relaxed deadlines, I don't have to deal with bugs, on-call shifts are non-existent, there's no real "emergency", and you get to know your users.

Joining Cloudflare has been a smart move because:

I use my writing skills to educate users on using products to build their applications.
I learn about cyber security.
I learn about Artificial Intelligence and other cutting-edge technologies.

My peace of mind has improved since shifting to technical writing, and I enjoy a better work-life balance.

Lifestyle and wellness

In 2023, I wanted to dedicate more time to improving my physical and mental wellness, with a slight focus on mental health, because it's easier to neglect.

How did I take care of my mental health?

Therapy

Seeing a therapist has helped me improve my self-esteem, gain new insights about my personality, and learn how to create boundaries with others.

Reduce social media consumption

Reducing social media consumption has helped me minimize exposure to harmful or triggering content, recognize and prioritize the value of real-life, genuine interactions.

Spending time in nature

When I'm not hitting the gym, I walk at one of London's many parks, and it's a great way to start my day.

Travel and exploration

I've been blessed enough to travel to two countries this year: Istanbul (Turkey) and Bali (Indonesia).

Of the two, I enjoyed my trip to Bali: I spent loads of time in nature (rice fields, forests, waterfalls, beaches), eating smoothie bowls, doing yoga, and massages.

I tried snorkelling in Indonesia, and it was an experience that allowed me to feel connected to nature.

Community and relationships

GT Scholars

GT Scholars is a social enterprise that runs programmes that help young people achieve their academic and career aspirations. I've been partnering with them since 2021, contributing to their blogging section on their website.

In 2023, I was the Lead Event Coordinator for a social mobility project dedicated to young boys, helping them gain the skills needed to succeed in their lives and careers.

This project ran for about three months, and it involved weekend workshops where the teenagers would group to learn about entrepreneurship, growth mindset, emotional intelligence, etc.

Black Woman in Tech Event

I was one of the panellists for Cloudflare's Black Woman in Tech event in October 2023. The event went better than expected, it felt like a conversation among friends, and there was a strong community feeling.

Conclusion

The overall theme for 2023 was about experiences. I experienced new hobbies, countries, people, and projects. I'm grateful for everything I experienced, and I hope 2024 will bring even more authentic experiences.

Happy New Year! 🎉

What Is Agile Software Development - How Does It Work?

Maddy — Mon, 18 Dec 2023 00:00:00 +0000

Agile software development has emerged as a transformative approach in software engineering, revolutionizing how teams conceive, plan, and execute projects. In a landscape characterized by rapid technological advancements and ever-evolving user needs, the traditional waterfall model often falls short of delivering the flexibility and responsiveness demanded by modern software development.

Agile methodology, born out of a need for adaptability and collaboration, provides a dynamic framework that prioritizes iterative progress, customer feedback, and constant communication among team members. This introduction aims to delve into the fundamental principles and key elements that define Agile software development, shedding light on its origins, core values, and the profound impact it has had on the efficiency and success of software projects.

What is Agile software development?

Agile is a way of creating software that focuses on flexibility and practicality in delivering the final product. It differs from traditional methods because it concentrates on building smaller parts of the software rather than the entire thing. This approach requires companies to change how they work.

There are several benefits to using Agile software development:

It helps teams adapt to changes while efficiently delivering what the business needs.
Agile encourages teamwork and a better understanding of everyone's roles.
Because testing happens throughout the development process, companies can be more confident in the product quality they release. This allows them to fix problems early on.

Agile has become more popular than the older "waterfall" method in many companies. However, there's a chance it might be overshadowed by the rise of DevOps, which focuses on collaboration between development and operations teams.

Why is agile so popular?

Agile is popular because it offers a flexible and effective way of working. Agile started in software development, where teams used it to speed up their projects and shorten the time between creating new products. Many other types of companies are also adopting Agile to make their work faster and more adaptable to the quickly evolving future.

A study conducted by Organize Agile found that nearly half of all organizations in 19 countries have been using Agile for three years or more. This shows how widely it's being adopted across different industries.

How does Agile software development work?

1. Define the project

The team and the customer set the project's goals, objectives, and requirements.

2. Create a backlog

This is a prioritized list of tasks that need to be done. The customer, product owner, and team collaborate to create this list.

3. Plan the sprint

The team chooses the most important tasks from the backlog and decides how much work can be done in a set period (called a sprint).

4. Execute the sprint

The team works on completing the chosen tasks during the sprint, holding daily meetings to track progress and solve any problems.

5. Review and demo

At the end of the sprint, the team shows the completed work to the customer and gathers feedback.

6. Retrospect

The team discusses what went well, what didn't, and what can be improved for the next sprint.

7. Repeat

This process continues for each sprint until the project is finished. The product is developed and delivered in smaller portions.

8. Continuously improve

Agile encourages ongoing improvement. The team reflects on its progress and makes changes to enhance processes, tools, and communication for future sprints.

Core Principles of Agile Software Development Methodology

The Agile software development methodology is guided by several core principles that make a process Agile:

Iterative Development

Projects are broken into short cycles (iterations) where small parts are developed and delivered. This allows for continuous improvements and feedback.

Customer Collaboration

Regular interaction with customers and stakeholders ensures the project meets their needs. Working closely with them helps refine requirements and prioritize tasks.

Adaptive Planning

Agile doesn't rely on strict upfront planning. Instead, it welcomes changing requirements and adjusts plans accordingly, enabling teams to respond to changing situations effectively.

Continuous Feedback

Agile thrives on frequent feedback loops. Regular reviews and retrospectives help teams identify areas for improvement, fostering a culture of continuous learning.

Empowered Teams

Agile gives cross-functional teams the freedom to make decisions. This autonomy boosts accountability, innovation, and a sense of ownership over the project's success.

These principles guide Agile, making it a top choice for many organizations globally.

Key Agile Development Concepts

Some important concepts in Agile development:

User Stories

These are functional units of work divided by the team with input from the client or product owner. Each user story contributes value to the final product.

Daily Meeting

The team gathers daily at a set time to share updates necessary for coordination.

Personas

In some projects, the team creates detailed profiles of hypothetical users of the product to understand their needs better.

Team

A small group of people working full-time on the same project or task is called a "team" in Agile.

Incremental Development

Agile teams prefer an approach where each product iteration improves upon the previous one by adding visible functionality.

Iterative Development

Agile allows for repeating and revisiting development activities, intentionally incorporating iterative cycles.

Milestone Retrospective

After working on a project for a while, the team sets aside time, typically one to three days, to reflect on key moments and lessons learned.

These concepts are fundamental to Agile and are used to ensure efficient and effective development processes.

Popular Tools in Agile Software Development

Extreme Programming (XP)

XP is a framework that helps teams create high-quality software by emphasizing proper engineering practices. It's useful for handling changing software requirements, working in small, closely-knit teams, and utilizing automated unit and functional tests.

Kanban

This method is used to visualize, manage, and improve workflow. Kanban helps organizations see their work progress and limits work in progress. It's beneficial when work arrives unpredictably and needs immediate deployment without waiting for other tasks.

Lean

Lean consists of tools and principles to identify and eliminate waste to speed up process development. It focuses on maximizing value while minimizing waste and is applicable across various industries that generate waste.

Scrum

Scrum is a framework teams use to set hypotheses, test them, reflect on the outcomes, and make adjustments. It allows teams to adopt practices from other frameworks as needed. It's popular among cross-functional teams working on product development, dividing work into iterations lasting 2-4 weeks.

Crystal

Crystal emphasizes people and interactions over tools and processes. It aims to streamline processes and optimize work by recognizing that each project is unique and dynamic. It's utilized when improving team communication, integrating continuously, involving active users, and adapting processes are essential.

These tools and frameworks are widely used in Agile software development to improve processes, collaboration, and product quality.

The Waterfall Model in Agile Software Development

The waterfall model is an older approach to making software. It involves following steps one by one and only moving on to the next step once the previous one is done.

Let's look at the steps of the waterfall model:

Requirement Gathering and Analysis: Everything the system needs to do is collected and written down.
System Design: A plan is made for how the system will work based on the requirements collected earlier.
Implementation: Small parts of the system are built and tested separately. These parts are then put together.
Integration and Testing: All the parts are assembled and tested to ensure they work well together.
Deployment of System: Once everything works correctly, it's made available for the customer or released in the market.
Maintenance: Fixes and improvements are made as needed, handling any issues that come up after the system is in use.

Not every project fits perfectly into the waterfall model or Agile methods. Sometimes, a mix of both, called Agile-Waterfall, works best. For instance, planning and design might follow a waterfall method while development uses Agile's shorter cycles.

Disadvantages of the waterfall model

Certainly! Here are the drawbacks or disadvantages of the waterfall model in simpler terms:

Late Software Development: In the waterfall model, working software isn't created until later in the project timeline.
High Risk and Uncertainty: There's a significant amount of risk and uncertainty due to the linear nature of the model, which doesn't adapt well to changes.
Not Suitable for Complex or Object-Oriented Projects: It's not the best fit for complex projects involving object-oriented software development.
Unsuitable for long or ongoing projects: The waterfall model isn't well-suited for lengthy or continuous projects due to its rigid structure.
Difficult progress measurement: Measuring progress accurately within different stages of the project is challenging.
Inflexibility in handling changing requirements: It's hard to accommodate changes in requirements once a stage is completed.
Lack of focus on end-user/client needs: The model might not prioritize or focus enough on meeting the needs of the end-users or clients.
Delayed testing until project completion: Testing is often delayed until the entire project is finished, which can lead to potential issues being discovered late in the process.

Conclusion:

In conclusion, Agile software development stands as a beacon of innovation in the dynamic world of software engineering. From its inception to widespread adoption, Agile has proven to be more than just a methodology; it's a mindset that embraces change, values collaboration, and puts the customer at the forefront of the development process. Agile's iterative nature accelerates project delivery and enhances the ability to respond swiftly to shifting requirements and emerging challenges. Agile remains a cornerstone for fostering adaptability, resilience, and customer satisfaction as technology evolves. In essence, the principles of Agile software development serve as a guiding philosophy, steering development teams toward a future where flexibility, collaboration, and continuous improvement are not just aspirations but integral components of successful software delivery.

If you enjoyed this article, subscribe to my FREE weekly newsletter.

Faqs

What is Agile?

Agile is a flexible and adaptive methodology used to manage projects. Its core focus is on prioritizing adaptability and continuous improvement rather than rigidly following a fixed plan.

What are the Four Principles of Agile?

The four guiding principles of Agile are valuing individuals and their interactions, emphasizing working software, fostering customer collaboration, and being responsive to change. A typical example of Agile methodology is Scrum.

Can you give an example of Agile?

Scrum is an instance of Agile methodology, a framework utilized to manage and accomplish intricate projects. It's commonly applied in software development but can extend to other fields. Scrum aligns with Agile principles, emphasizing flexibility and continuous enhancement. It utilizes short iterations, known as sprints, to monitor and handle progress.

What is the Core Concept of Agile?

The fundamental idea behind Agile is to prioritize adaptability and continuous improvement above rigid planning. Agile methods aim to swiftly and effectively deliver functional software by being adaptable and responsive to evolving requirements and priorities. Additionally, Agile stresses collaboration among teams, customers, and stakeholders, promoting open communication and transparency throughout a project's lifespan.

How Software Developers Can Become Better Writers

Maddy — Mon, 27 Nov 2023 07:00:00 +0000

Software developers are known for being great programmers but bad writers. This is fair since coding is the software developers' core skill.

However, software developers contribute to internal or external documentation in many companies. And this is where software developers struggle.

This article shares tips to help you become a better writer and create better documentation.

1. Know your audience

Knowing your audience means understanding who you're writing for. Are you writing for experienced people or beginners?

Knowing your audience helps you evaluate whether you need to include or omit certain information.

For example, if you're writing content on "How to send an HTTP PUT request", you may want to specify what HTTP means if you're writing for beginners. If you're not, you can omit the information and your readers will still understand your content.

2. Be user-oriented

Technical writers are user advocates. They care about the user experience. If you want to improve your writing, keep your reader in mind throughout your writing process.

Writing user-oriented content means responding to users' intent.

If you want to write user-oriented content, respond to users' intentions - meet their needs before they realize they have them, and always be one step ahead.[Delante]

3. Logically structure your content

Structuring your content logically means laying out information so your reader can smoothly jump from paragraph to paragraph. Logical content feels clear and confusion-free.

Readers dont want bumps, unintended surprises or to feel threatened in any way. They dont want to follow a train of thought, only for it to lead to a dead-end, or for a new idea to be dumped on them without warning.[The Writers College]

How can you achieve a logical flow in your content?

Outline your ideas: Write the information you want your user to know on a piece of paper or editor. This step helps you clearly understand what you want to write.
Plan the flow of your writing. This step helps you visualize what works and what doesn't before you start writing, potentially saving you time.
Address each point at a time, and ensure there's a clear connection between paragraphs.
Use subheadings. Some readers read thoroughly, and other readers are skimmers. Write for both types of readers.
Use lists: use bulleted and numbered lists. Use bulleted lists when you want to list facts. Bulleted lists are ideal when the order doesn't matter. Use numbered lists when the order is essential.

4. Format your content

Formatting means how you want your content to appear. Formatting includes headings, subheadings, paragraph length, links, etc.

To format your content:

Use code blocks where necessary.
Break down lengthy paragraphs into shorter paragraphs.
Use H1, H2, and H3 subheadings accordingly.
Use tables to simplify content and data.
Edit and proofread. Editing and proofreading can be partially automated. Look for grammar and spelling errors. Ensure consistency in style and tone.

5. Write concisely

Concise writing means using the fewest words possible to convey an idea clearly.[Grammarly]

Some examples to help you write more concisely:

Eliminate unnecessary words such as in order to , and that. In order to is unnecessary 99% of the time. Replace it with To. For example, In order to install , would be To install.
Replace vague words with specific ones. For example, This helps you delete the branch without removing the entire history should be X command helps you delete the branch without removing the entire history. Being specific helps you avoid confusion and misunderstandings from the reader.
Use active voice as much as possible.

Conclusion

After reading this article, you have everything you need to become a better writer. Consider reading the following articles to learn more about writing:

Consider subscribing to my FREE weekly newsletter, I share useful content there!

Top 6 Essential Technical Writing Skills

Maddy — Wed, 22 Nov 2023 07:00:00 +0000

Technical writing goes beyond relaying information. It's about crafting a seamless experience for the reader.

This article delves into the essential skills that every technical writer should possess, from mastering the fundamentals of grammar and style to adapting content for diverse audiences.

Communication

Communication is the core skill of a technical writer. Communication is made of written and verbal communication. Technical writers need written communication skills to convert complex information into easy-to-understand documentation.

Technical writers need verbal communication to communicate with immediate team members and stakeholders.

Teamwork

Technical writing is a job that needs cross-functional effort.

Documentation is written and maintained by a team of technical writers and members of other teams (such as content designers, software engineers, product managers, and more).

[...]A user guide can only be clear and make sense when its author knows how everything works. So, theres always a lot of communication and inquiries about all sorts of things.[ClickHelp]

Documentation as Code

Documentation as code (also known as Docs as Code) is a process to create and publish documentation.

Documentation as code uses the same tools and processes in the software development lifecycle, with the main difference being documentation instead of code. These tools and processes are:

Git (Version Control).
Code Reviews (where another technical writer reviews your documentation before merging).
Automated Tests.
Issue Trackers (such as JIRA).

Documentation as code fosters a culture of ownership and collaboration.

User experience

Technical writers are user advocates and play a massive role in the success of a product. They understand what the audience needs and write directly for them. Technical writers know what information users need to make the most out of the product and use that information to create the documentation.

Research skills

Technical writers spend a lot of their time researching. Researching includes:

Audience Analysis: this type of research helps the technical writer understand the target audience.
User Experience: this type of research helps the technical writer understand the readability of technical documentation.

Editing skills

Besides writing, technical writing involves a lot of editing. Editing includes:

Content review.
Spelling and punctuation (although this step can be partially automated).
Proofreading.

Conclusion

After reading this article, you've learned about essential technical writing skills.

If this article was helpful to you, consider subscribing to my FREE weekly newsletter, where I share more insights like this.

Technical Blogging VS Technical Writing: Main Differences

Maddy — Wed, 04 Oct 2023 05:30:00 +0000

Technical blogging and technical writing are often used interchangeably but are two different writing styles.

Even though they share a common goal of effectively communicating with the reader and wanting to provide value, blog writing and technical writing serve two different purposes.

This blog will explain the differences between technical blogging and technical writing.

Purpose

Technical blogging aims at engaging the reader and providing valuable information in an entertaining and conversational manner.

Technical bloggers want to connect with the audience and create a sense of community. Technical bloggers adopt techniques such as descriptive language, catchy headlines, and engaging introductions. Technical bloggers tend to write content that's SEO-optimized.

Technical writing's main purpose is to convey complex information clearly and concisely.

Technical writers ensure the reader understands and can effectively use the presented information. Technical writing requires high precision and attention to detail to ensure the content is accurate, logical and easy to follow.

Technical writers also focus on usability and accessibility. They organize content to allow users to find the information they need and navigate the content effortlessly.

Read 3 Things You Can Do To Improve Your Technical Writing Skills to learn more.

Voice

Technical blogging is a style of writing that allows you to share your voice. Your writing style represents your voice and your thoughts.

In technical blogging, you use pronouns such as "you", "I", and "we". Some blog writers also use slang and swearing in their writing style to better relate and engage the user. Technical blogging tends to be more wordy compared to technical writing.

Technical writing is different. Technical writing is a sterile form of writing whose main focus is to guide the user into learning how to use a product. You use the company's voice to address the user in technical writing.

An example to show you the difference between blog writing and technical writing is this:

Technical blogging : "I recommend you use X to achieve Y".

Technical writing : "X company recommends using X to achieve Y".

Technical blogging : "Make sure you install X to view Y".

Technical writing : "Install X to view Y".

Read Top Skills To Become A Tech Blogger to learn more.

Structure

Technical blogging doesn't follow a strict structure. Often, bloggers use their voice as a style guide. Technical bloggers have a flexible and creative approach to structure and organization.

Technical bloggers can experiment with different formats like listicles, how-to guides, etc. The structure is driven by what they want to achieve with their content.

In technical writing, writers follow a well-defined style guide. The company's Head of Content (or someone senior) usually creates this style guide. Each page needs to follow a specific structure.

Technical writers follow industry-specific terminology, ensure content is organized logically and follow a step-by-step approach.

Read Why User Documentation is Essential in Software Development to learn more.

Tone

In technical blogging, the tone is informal and conversational. Technical bloggers adopt a friendly and relatable tone as if conversing with the reader.

Technical bloggers know how to convey empathy through their words, establish a connection and build trust with the audience.

In technical writing, the tone is formal and precise. The tone is objective and focused on delivering information accurately and concisely.

Technical writers prioritize clarity and avoid adding information (or words) that provide no value to the reader.

Conclusion

After reading this article, you know the difference between a tech blogger and a tech writer. Which one are you?

P.S.: if this article was helpful to you, subscribe to my FREE weekly newsletter.

Until next time!

Most Common Misconceptions About Software Engineers

Maddy — Mon, 25 Sep 2023 09:17:42 +0000

Software engineers are often misunderstood. These highly skilled professionals are the wizards behind the digital curtain, developing the applications and programs that drive our modern world. Unfortunately, several common misconceptions about software engineers persist in popular culture.

This article will debunk the top five common misconceptions about software engineers and shed light on their abilities and responsibilities.

Let's start.

Misconception #1: Software engineers only work on coding

Coding is the core skill you need to possess to become a software engineer. Coding is how you tell the computer how to solve a problem. However, software engineering is not all about coding. Your day will also involve:

Meeting with your colleagues, manager, and stakeholders.
Presentations.
Writing documentation.
Writing tests.
Oncall shifts.

Misconception #2: Software engineers always work on shiny new code

A lot of software engineering work is maintenance work.

Maintenance work means that you will work on adding, removing, or updating lines of code on an existing codebase.

This existing codebase is also known as legacy code. Legacy code is code someone else has written (usually employees no longer in the company), which you must take responsibility for.

Legacy code can be rewritten using better programming paradigms, and this is where software engineers provide fantastic value.

It is not an easy task.

Misconception #3: Software engineering is easy money

Unfortunately, social media has spread the idea that software engineering is easy, allowing you to make a six-figure salary relatively quickly.

This is far from the truth because:

It isn't easy to find entry-level jobs. Most jobs available out there are for experienced engineers.
Compensation depends on location, seniority level, size of the company, etc. Big Tech companies are known for paying top-of-the-market salaries. However, they do not represent the entirety of the industry in terms of compensation.
It takes experience, a bit of sacrifice and knowing how to negotiate to reach a specific salary.

Misconception #4: Software engineering is a solo job

Software engineering is a team sport. Teamwork is a skill that all software engineers should possess and master.

Teamwork is about asking what you can do for your team, as much as it is about asking what your team can do for you, and its this harmony that forms the very foundation of teamwork as we know it today. Its about recognising how our skills and actions affect our team, as well as our own individual performance, and its also about adopting an attitude that leans on courage, self-love, appreciation, surrender and sacrifice.[The Benefits of Teamwork and Collaboration in Software Development]

Teamwork includes:

Open communication.
Having the right tools.
Writing high-quality documentation.

Misconception #5: Software engineers can work from anywhere

In theory, yes. Software engineers only need a laptop, comfortable office equipment and reliable and fast WiFi.

However, whether a software engineer can work depends on the company and the manager. It is not a decision that a software engineer can make on his own.

Unfortunately, many companies force employees back to the office 2-3 times a week. Another consideration to make is that remote working does not necessarily mean you can work from anywhere in the world because:

Time zones can pose a challenge to communication.
Taxes can limit your chances of working in any country.

Misconception #6: It's a stable job

2022 and 2023 have been filled by massive layoffs, even from companies with solid performance. This has shown that software engineering (and other positions) are unsafe. You can lose your job at any time.

Conclusion

Do you agree with the misconceptions above? Let me know in the comments.

P.S.: if this article interests you, subscribe to my FREE weekly newsletter!

Related resources:

Day In The Life Of A Technical Writer

Maddy — Tue, 12 Sep 2023 05:00:00 +0000

Technical writing is not just about writing. It's a job that involves a series of different tasks. Each day is different. However, there are some tasks that technical writers perform almost every day.

This article describes a day in the life of a technical writer (order may vary from person to person and from day to day).

Email checking

Like many other jobs, checking emails is part of the day for a technical writer. Most of my emails come from GitHub notifications and the company's internal emails.

Pick a task

Many companies use JIRA as a project-tracking software. JIRA is where I manage all the tasks for the current or future Sprints. I look at my JIRA to plan my day and pick a high-priority task for the upcoming Sprint.

Research

My job involves writing documentation for a developer audience. I research and learn new concepts every day. I research the product, watch YouTube videos to clarify concepts, and read blogs to fulfil my curiosity.

Cross-functional collaboration

Cross-functional collaboration is a crucial part of the job of a technical writer.

Cross-functional collaboration means running a project with the help of teams from other parts of the organization.

[...]Technical writing requires a different skill set than programmingask anyone who has read documentation written by developers. Similarly, there are few tech writers who could seamlessly take on coding tasks. Writing tasks therefore tend to be isolated from the rest of development work and remain the responsibility of writers.[Orckestra]

In my case, cross-functional collaboration happens with content designers, UX designers, software engineers, and product managers.

Write the documentation

Once you have enough information to create documentation, you start by following the company's style guide to create guides, tutorials, etc.

Submit documentation for review

Like in software engineering, before your changes reach production, they'll have to go through a review process from your peers to ensure documentation is up to standard.

Review your peers' pull requests

In software engineering, there is a code review process before your changes can be merged into production.

The exact process happens in technical writing: you support your colleagues by reviewing their pull requests so they can also carry on with their work.

Organize your JIRA

JIRA is a valuable tool. However, if not kept organized, it loses the benefits that it offers.

Organize your JIRA by:

Giving descriptive names to your tickets. For example, include the name of the product(s).
Adding descriptions to each ticket.
Adding any labels.
Adding points to each ticket.

Attend meetings

Meetings can be with SMEs (Subject Matter Experts), colleagues, and stakeholders. They can also be company-wide meetings.

Conclusion

After reading this article, you know what the day of a technical writer looks like.

Are you a technical writer? Do you agree with the article?

If this article is interesting to you, subscribe to my FREE weekly newsletter.

Related resources:

How To Write A Technical Blog Post (Template)

Maddy — Mon, 11 Sep 2023 15:55:49 +0000

In this article, I'll cover everything you need to know about writing a technical blog to make it easier for you to create your following articles. This article suits those who write a lot of tutorial-style technical blog posts.

What is a technical blog post?

A technical blog is written content focused on sharing knowledge and teaching the user a technical subject. Most technical focus on teaching a user how to use a technology.

How to write a technical blog post

A technical blog should have at least three main sections: an introduction, a body, and a conclusion.

Introduction

The introduction is a short paragraph under the blog post title.

The introduction is where you tell the users what you will teach them. In this section, you should tell your readers what to expect when reading the article.

Ideally, the introduction should be 3-5 sentences long.

You may want to add a "Prerequisites" section depending on your topic. In the prerequisites section, you tell the user what they must have installed on their laptops before they can start the tutorial.

You must add this section to ensure your readers can complete your tutorial.

Body

The body of your technical blog is where you'll dive deeper into the topic you want to cover.

Step-by-step approach

If you write tutorial-style blog posts, use a step-by-step approach for better readability.

The user should accomplish one task for each step.

For example, if you're telling the reader to "Install Node.js and write a class", you should have one step named "Install Node.js", and the following step should be "Write a class".

Use visuals

Ideally, each step should be accompanied by screenshots, code snippets, and videos. Visual content helps the reader retain more information.

Follow a logical order

If you write step-by-step tutorials, the steps must follow a logical order. Otherwise, you risk creating a negative experience for the user trying to learn a new subject.

A good example is:

Install Java.
Write a class.
Create an object.

You do not:

Write a class.
Install Java.
Create an object.

Conclusion

In the conclusion, you tell users what they have learned at the end of the technical blog post. In the conclusion, you can add:

Links to your social media (GitHub included) to follow you.
A link to your newsletter to subscribe to.
A "Related resources" section where you share links that could help your readers.

Key Takeaways

After reading this article, you know how to write a technical blog post. This template should help you write technical blog posts faster.

If you enjoyed this article, subscribe to my FREE weekly newsletter.

Related resources:

Lessons Learned In 2 Years of Blogging

Maddy — Tue, 15 Aug 2023 07:55:08 +0000

Exactly two years ago, I started my blogging journey.

I started with the following:

No readers.
No blog posts.
No blogging experience.
No SEO understanding.

Two years after I've accumulated:

10k+ monthly readers.
100+ blog posts.
A ton of blogging experience.
Good knowledge of SEO best practices.

In this article, I'll share what I've learned in 2 years of blogging.

Let's start.

Stay consistent

"Stay consistent" will sound like a cliche, but successful blogging is more about consistency than anything else.

Staying consistent doesn't mean publishing an article daily (which I believe is unsustainable).

It means you stick to a blogging schedule that suits your needs and lifestyle.

Whether you decide to publish an article per week, every two weeks, or monthly, stay consistent with what you choose.

Blogging takes time

It took me just over 12+ months to reach 10k readers every month.

There's no overnight success when it comes to blogging.

Read How To Increase Your Blog's Traffic in 3 Easy Steps to learn how to increase your monthly traffic.

Blogging is still relevant in 2023

ChatGPT was released on the 30th of November.

When ChatGPT was launched, a lot of people believed it was going to make blogging obsolete.

This is far from the truth. Blogging has (and it will) evolved and changed.

I read a lot of online content and recognize when an article is AI-generated to manipulate the search engine.

Using automationincluding AIto generate content with the primary purpose of manipulating ranking in search results is a violation of our spam policies.[Google Search Central].

There's always so much to do

When I started my blog and had under 20 blog posts, it was easy to go back and update/delete/change content.

The more you add content to your blog, the more challenging it becomes to stay on top of the many tiny changes that make your blog better and improve SEO.

To combat this, I try to set aside some time during the week (ideally an hour) to update the most read blog posts.

Updating content means:

Adding internal linking.
Making sure information is still relevant.
Adding/editing images (or visual content).
Updating/deleting broken links.

Read Pros And Cons Of Running A Blog to learn more about the advantages and disadvantages of running a blog.

You don't always write for yourself

To grow your blog, you must write content addressing your audience's needs.

A successful blog is a blog that answers people's questions and concerns.

This means that you won't always write for yourself.

You'll have to find a balance between enjoying writing content for yourself and your audience.

Read Lessons Learned In 12 Months of Blogging

Only accept collaborations that suit your blog

Blogging brings many collaborations opportunity.

From time to time, you'll receive partnership opportunities in your inbox. However, not all partnerships are worth working with.

Your readers can sense when you want to monetize your blog, even though that means collaborating with brands that don't suit your blog.

Read Things I Wish I Knew Before Starting A Tech Blog

Treat your blog like a business

While blogging still hasn't allowed me to quit my 9-5 job, it has become a little side hustle that I treat like a business.

Ensure you have a dedicated business email for your blog. Communicate professionally with brands, whether you decide to collaborate with them or not.

Conclusion

I hope this article helps you! If it does, subscribe to my FREE weekly newsletter.

Happy blogging!