Kickstarting your tech writing career with open source

After graduating from University in the midst of a pandemic, I knew that I wanted to be a tech writer, but I wasn’t sure how to start. Google Season of Docs was the perfect way to launch my career; it let me work on my own terms and led to me starting my own business and to subsequent tech writing jobs in open source. I am currently working as a tech writer at Google and volunteering for documentation-related open source projects.

Should you join an open source project?

The charm (and challenge) of open source is that the line between creators and users becomes blurred. Do you wish that your beloved tool had that one feature you really need? You can add it yourself! Other users might support your feature request and may even help you build it. Before you know it, you’re part of a wonderful community bound together by passion.

People join open source projects for many reasons:

• They believe in the vision of a project and want to help build it
• They want to build professional and technical skills
• They are motivated by the possibility of hundreds—or even thousands—of people using their work

Life in open source as a tech writer

Many contributors in open source come from a software engineering background. They are great at building software, but they sometimes struggle with documentation. Through Google Season of Docs, open source projects can hire technical writers to help them create much-needed content. These technical writers are likely the first person in the project working exclusively on educational content—which comes with ups and downs.

The fun parts

As an open source technical writer, you will often be in close contact with your users. Through researching user needs, technical writers develop more empathy for the struggles of the users. Many tech writers (myself included) find that this closeness helps them write better.

Contributing to open source also allows you to create documentation in different contexts. For example, you might have authored content in a CMS in the past—diving into an open source project gives you the opportunity to explore a docs-as-code workflow. Another circumstance could be that you wrote documentation in a different industry and you want to see what it’s like to document software. Changing up your writing routine helps you find more creative ways to tackle problems for the next project you work on.

The hard parts

Documentation quality can be quite variable in open source. While some pages might be really useful, others might be outdated, don’t follow the user workflow, or cover way too much information on one page. Making sense of the existing documentation landscape can feel like a daunting task.

Most open source projects suffer from gaps in the documentation. Since open source developers are so enmeshed with their code and the project, they have a lot of context, and suffer from the “curse of knowledge”. It’s hard for contributors, or anyone who has held a position for a while, to remember what it was like to be a beginner or new to a project. When developers write documentation, their brain auto-completes what is missing on the page.

Because many people work on open source for personal satisfaction, you might experience pushback from people who are protective of their documentation. I find it helpful to view pushback as an act of caring about documentation. Take a closer look at why you are receiving pushback:

• Do the developers have concerns about your technical understanding?
• Are they not ready to let go of their document?
• Do you have different ideas of who the user is and what their goals are?

Understanding developer concerns can help you reach the shared goal of improved documentation.

Succeeding in Google Season of Docs and beyond

These tips helped me make the most of my Google Season of Docs experience.

Gain clarity

Take time in the beginning of the project to really understand the software, the user’s needs, and your docs landscape. (I allocated one third of my entire project timeline to gaining clarity.) Talk to your project mentors, do user research, and perform a content audit—this will help you understand the current structure and identify weaknesses and gaps in the content.

Keep your community in the loop

Open source communities attract contributors from all over the world—which means communication is usually asynchronous and in writing. Transparent communication is a must to keep your users (and potential co-creators) engaged. When they know what’s going on, it’s easier for them to chip in.

Deal with pushbacks

Transparent communications and a solid documentation plan go a long way towards addressing concerns. It’s easier to receive support if your team knows what you’re doing.

Build a professional support network

Find other tech writers to geek out with, especially if you’re the only technical writer in your project. Groups like Write the Docs and The Good Docs project are good places to find like-minded people to brainstorm and learn with.

I hope you find a project that interests you and the bandwidth to participate in Google Season of Docs. It was a worthwhile experience for me, helped me advance in my career, and I hope the same for you.

P.S. You can find a detailed write up of my work for Season of Docs ‘21 on my website.

By Tina Luedtke, Technical Writer – Google

Configure your private clouds using the Google Cloud VMware Engine IaC Foundations repository

Introduction

Google Cloud VMware Engine is a Google-managed VMware platform that customers can use to run their VMware workloads on Google Cloud. VMware Engine private clouds consist of VMware ESXi clusters that are managed by Google. Customers manage the virtual infrastructure of private clouds using VMware vCenter and VMware NSX-T for software-defined networking. The GCVE IaC Foundations code guides customers to automate the configuration of several layers of the infrastructure and virtualization stack, using infrastructure as code. This includes the integration of platform logging and monitoring with the Google Cloud Operations Suite, configurations such as VM folders, permissions and VM deployments in vCenter and network configurations in NSX-T, including subnets, firewalls, and load balancers.

The use of infrastructure as code for a VMware Engine Private Cloud offers multiple benefits, including:

1. Providing consistent and repeatable deployment templates which can be reused across SDLC environments to reduce human error and shorten configuration times.
2. Enabling continuous integration using GitOps workflows to improve collaboration between engineers and increase reliability in the release process.
3. Offering version control of configuration templates to track changes in the infrastructure and a simple method to revert changes to a previous configuration.

Technical Details

The Google Cloud VMware Engine IaC Foundations Github repository contains Terraform modules and sample code for maintaining VMware Engine, vCenter and NSX-T configurations using infrastructure as code. The repository is structured as follows:

├── examples
│   ├── nsxt-gateway-firewall
│   ├── nsxt-load-balancer-pool
│   ├── nsxt-load-balancer-service
│   ├── ...
├── modules
│   ├── nsxt-gateway-firewall
│   ├── nsxt-load-balancer-pool
│   ├── nsxt-load-balancer-service
│   ├── ...
└── stages
    ├── 01-privatecloud
    ├── 02a-nsxt
    ├── 02b-vcenter
    ├── 03-vms
    └── 04-load-balancing

The modules directory contains the Terraform IaC modules for GCVE (vCenter & NSX-T) resource types. Each module has a corresponding example in the examples directory. Modules and examples are meant to be discrete and function as the building blocks for managing GCVE at scale.

The stages directory contains sample deployments composed from modules for each of the different stages of the foundational deployment. These stages should be executed in the order they are listed. Stages may also be delegated to different teams within an organization depending on organizational roles and responsibilities. As an example, there may be a team that manages vCenter, while a Networking team manages NSX-T and each team has their own code repository for configuration management.

The individual stages deploy the following components:

Stage	Deployed sample Component(s)
01-privatecloud	Google Cloud Monitoring & Logging integration for GCVE
02a-nsxt	Virtual machine network segment North / south firewall (gateway firewall) East / west firewall (distributed firewall)
02b-vcenter	vCenter resource pools & folders vCenter role assignments
03-vms	Virtual machines
04-load-balancing	NSX-T Load balancing

Deployment Walkthrough

To deploy the sample stages you will need to clone the gcve-iac-foundations repository and have Terraform 1.3.x or later installed.

To deploy the stages proceed in order in the stages directory from 01-privatecloud until 04-load-balancing. In each directory perform the following:

• Copy terraform.tfvars.example to terraform.tfvars and customize any values as necessary
• Run `terraform init`, `terraform plan` and `terraform apply`

Each of the stages and examples contain reference terraform.tfvars files which can be used in the initial stages to test deployment and later customized to meet specific requirements.

As an example, the following Terraform configuration can be used to configure the NSX-T distributed firewall:

dfw_policies = [
  {
    display_name    = "dfw_allow_policy"
    sequence_number = 1
    rules = [
      {
        action             = "ALLOW"
        destination_groups = ["10.123.1.0/24"]
        source_groups      = []
        direction          = "IN_OUT"
        display_name       = "dfw-allow-ssh"
        logged             = false
        services           = ["SSH"]
      },
      {
        action             = "ALLOW"
        destination_groups = ["10.123.2.0/23"]
        source_groups      = ["10.200.1.0-10.200.1.128"]
        direction          = "IN_OUT"
        display_name       = "dfw-allow-dns"
        logged             = false
        services           = ["DNS"]
      },
    ]
  },
<…snip…>
]

Apply the Terraform configuration from a terminal using

terraform init // initialize the provider and modules
terraform plan // validate the expected Terraform configuration on the console
terraform apply // deploy the configuration in NSX-T

Try it yourself

Whether you consider using VMware Engine for your VMware workloads or you actively use the service already, give it a try and clone the repository into your environment and go through the provided deployment examples and stages of the repository. Review if you can automate any processes that you perform manually today using infrastructure-as-code and improve your VMware operations using the content from the foundations repository.

We would like to get your feedback! If you encounter any issues or you have any feedback or suggestions for improvement, create an issue directly on the repository on Github. We would also like to encourage you to create pull requests to the main branch if you like to become an active contributor. To get started, review how to contribute on Github.

By Konrad Schieban and Jason Steenblik – Google Cloud

Acknowledgments:

Thank you to the following team members who made this solution possible: Kumari Renuka, Ashwin Naik, Leandro Carracedo, Eric Danan, and Umesh Kumhar from Google Cloud.

Mentor organization applications are open for Google Summer of Code 2023!

We are excited to announce that open source projects and organizations can now apply to participate as mentor organizations in the 2023 Google Summer of Code (GSoC) program. Applications for organizations will close on February 7, 2023 at 18:00 UTC.

As 2023 begins, so does our 19th year of Google Summer of Code! Last year, we had a few updates to the program that will continue for the 2023 program year. Our most noted change coming in 2023 is that we are expanding the program to be open to students and to beginners in open source software development. We are also continuing our increased flexibility in the length of the projects—offering 175 and 350-hour projects—and the ability to extend the program from the standard 12 weeks up to 22 weeks.

Does your open source project want to learn more about becoming a mentor organization? Visit the program site and read the mentor guide to learn what it means to be a mentor organization and how to prepare your community (hint: have plenty of excited, dedicated mentors and well thought out project ideas!).

We welcome all types of organizations and are very eager to involve first-timers with a 2023 goal of welcoming 30+ new orgs into GSoC. We encourage new organizations to get a referral from experienced organizations that think they would be a good fit to participate in GSoC.

The open source projects that participate in GSoC as mentor organizations do all kinds of interesting work in security, cloud, development tools, science, medicine, data, media, and more! Projects can range from being relatively new (about 2 years old) to well established projects that started over 20 years ago. We welcome open source projects big, small, and everything in between.

One thing to remember is that open source projects wishing to apply need to have a solid community; the goal of GSoC is to bring new contributors into established and welcoming communities. While you don’t have to have 50+ community members, the project also can’t have as few as three people.

You can apply to be a mentor organization for GSoC starting today on the program site. The deadline to apply is February 7, 2023 at 18:00 UTC. We will publicly announce the organizations chosen for GSoC 2023 on February 22nd.

Please visit the program site for more information on how to apply and review the detailed timeline for important deadlines. We also encourage you to check out the Mentor Guide, our new ‘Intro to Google Summer of Code’ video, and our short video on why open source projects are excited to be a part of the GSoC program.

Good luck to all open source mentor organization applicants!

By Stephanie Taylor, Program Manager – Google Open Source Programs Office