[2020] Season of Docs // Free resource for writing proposals

Season of Docs is a 3-month program organized by Google that connects tech writers to open source organizations. The goal of this program is to help open source organizations improve their documentation and help tech writers contribute docs to open source projects and earn a stipend while doing so.

Although I am not a mentor for the program this year, I have been receiving a LOT of messages from writers who want to participate in the program. So I made a video and created a resource to help writers make an informed decision about participating in the program. Here’s the video:

And if you haven’t already, sign up for my newsletter to get access to the proposal writing resource.


Why and how tech writers should work on their technical skills

A few weeks ago, I was invited as a guest on one of my favorite podcasts: 10-min Tech Comm. Check out my episode about why and how tech writers should work on their technical skills:


PS: Tom Johnson is hosting a poll based on the podcast. Cast your vote here: https://idratherbewriting.com/2018/08/10/how-much-time-devoted-to-learning-tech-is-needed/

Reader question: Contributing docs to open source projects

As you might know, I recently conducted a webinar about contributing docs to open source projects. In this blog post, I am answering few follow-up questions about the topic.

Vinaya Krishna asks:

How to acquire domain knowledge of these communities? (Since you work in Cockroach Labs, there are people who guided you there. But how did you start working on others? Is it just by browsing their pages? Or did you actually get KT from other fellow members?)

Acquiring domain knowledge of the project depends on the complexity of the project. For beginners, I would recommend that they start by just observing the projects that they are interested in – follow the repository, see which contributions are being made, participate in their communication channels (probably Slack or Gitter), and keep an eye out on the issues list. When you feel confident enough to make your first contribution, start small – pick the easiest issue you can find and get a win under your belt. This will help you get familiar with the process and tools, and then you can move on to handling the technical complexity of the project.

I cannot stress enough the importance of being self-motivated and self-reliant when contributing to open source projects. Remember that the project maintainers are most probably employed full-time elsewhere and are working on the project on their own time. We cannot expect them to handhold us through the project – so make sure to do your homework, try figuring stuff out on your own, and approach them only when absolutely necessary.

More details in the presentation: Contributing docs to open source projects

Can a for-profit organization use Github with their data confidential in it?

As far as I know, yes. So GitHub has two flavors: you can choose your GitHub repository private or public. The repositories that seek contributions are public repositories. But you can make your repositories private to keep your data confidential.

Can you please upload the PPT somewhere so that we can visit the links you had mentioned in the closing slides of PPT?

Yes! Here you go: Contributing docs to open source projects

Update: A helpful reader, Suzanne de Veld, suggested the following projects that accept contributions and other useful links:



Thoughts from Places: Write the Docs 2018 Portland

I recently attended the Write the Docs 2018 conference in Portland, Oregon. For those of you who don’t know, Write the Docs is a community for everyone who writes tech docs. I have been a part of the Write the Docs Slack community for quite some time now, and I have found immense value from the interactions on the Slack channels. I was excited to meet everyone in person and put faces to names (or Slack handles). And I was not disappointed 🙂

The conference is a four-day event that consists of a hike, the Writing Day, and two action-packed days of scheduled talks, lightning talks, unconferences, reception, social, and the job fair. Not being an outdoorsy person, I skipped the hike and joined the group on Sunday for the Writing Day.

Writing Day

Writing Day is a day meant for conference attendees to contribute to open-source docs projects. This was the day I was most excited about. The entire Docs team at Cockroach Labs had prepped and planned for weeks to set up our project for the Writing Day. During our brainstorming sessions, Rich had excellent suggestions about the types of documentation tasks our contributors could work on. Lauren worked tirelessly to create an incredible style guide to help people edit or write docs for our project. Jesse and I created detailed GitHub issues for tasks we had identified and labeled them with `wtd-writing-day`. And all the preparation paid off.

On the day, we had a full table (that is 6-7 contributors) at any given time. I was impressed by how dedicated our contributors were. While a couple of contributors were already familiar with GitHub and Markdown, most of the contributors had never worked with GitHub/Markdown before. But they were determined to learn the tools and contribute to our docs. They worked through our contributing guide and Getting Started docs and made substantial first contributions. By the end of the day, we had received several contributions and the contributors had successfully learned GitHub/Markdown. It was a win-win!

Takeaways from the talks and unconferences

Since I live-tweeted the talks and unconferences that I attended, you can view my key takeaways from the conference here:


In addition to this blog post, I attempted a vlog as well. Here it is for your viewing pleasure:

Survey: Contributing Docs to Open Source Projects

Thank you for the response to the Contributing Docs to Open Source Projects webinar!  You can help me better prepare for the webinar and make sure that you find it useful and answers your questions by filling in the following survey:

Oh, and if you haven’t registered for the webinar yet, here’s the registration link:



WTD update + Webinar announcement

I am back from my very first Write The Docs (WTD) conference in Portland. I represented Cockroach Labs at the Writing Day. We set up our project for open source contributions and the response was amazing! And we were in good company – the other open source Writing Day projects included Kubernetes, Write The Docs, and Netlify. I also met up with Mike Lewis from GitLab and had a productive discussion about their open source contribution process. To summarize, I am pumped up about all things open source docs, and want to share all I learned with you!

Which brings me to an exciting announcement: I am teaming up with Information Developers Foundation to conduct a webinar about “Contributing docs to open source projects”. This is a topic I am passionate about because I have benefited immensely from working with open source projects. But my pet peeve is that while everyone agrees that contributing to open source is a great idea, nobody really talks about how to actually go about it. What is an open source project? How do you get started with one? What do you need to know to make meaningful contributions? What are the things to look out for, or things not to do? I intend to answer all these questions and also walk you through a few open source projects I personally like. So join me on May 19 at 8:30 PM IST to discuss how to contribute to open source projects. Here’s the registration link:


Also, feel free to send in any questions or topic suggestions you might have and I will try to answer them in the webinar: