Category Archives: Google
For the past year I’ve been working with colleagues to create and run Google’s Season of Docs program. It’s super exciting that the first results are now out. There are more results to come in the new year, when the long-running projects finish.
Congratulations to the technical writers and open source mentors who’ve successfully completed their standard-length projects and good luck to those who’re working on the long-running projects. Also a big thank you from me, to everyone who’s taken part in this pilot of the program, including those who had to withdraw from the program for various reasons. It’s been a privilege to receive all the feedback from everyone involved and to learn from the experiences of so many people.
Results for Season of Docs 2019
This year’s Season of Docs included a limited number of technical writing projects, as a pilot to measure how well the program would be received. There are 36 successfully completed projects out of the 41 standard-length projects that finished in December 2019. Eight long-running projects are still in progress, scheduled to finish in February 2020.
The goals of Season of Docs are:
- Bring technical writers and open source projects together to improve open source documentation and thus to contribute to the excellence of open source products.
- Give technical writers around the world the opportunity to work in open source and to learn about open source processes, tools, products, and code.
- Help open source projects understand how technical writers work and what technical writers can contribute to the open source projects.
- Improve the overall experience of contributing to open source, by providing excellent documentation for new contributors.
Season of Docs 2019 participants come from round the world, including all continents except Antarctica.
What are the participants saying about their experiences so far? Here are a few quotations from the blog posts and reports that people have published.
- From technical writer Kartik in a blog post, Experience in Google Season of Docs 2019 with Apache Airflow:
I also started getting invited in the PR reviews of other developers. I am looking forward to more contributions to the project in the coming year.
- From technical writer Elena in the project report, Apache Airflow: Documenting using local development environments:
I’m deeply grateful to my mentor and Airflow developers for their feedback, patience and help while I was breaking through new challenges (I’ve never worked on an open source project before), and for their support of all my ideas! I think a key success factor for any contributor is a responsive, supportive and motivated team, and I was lucky to join such a team for 3 months.
- From technical writer Aaron, quoted in a blog post by open source mentor Olivier Hallot, The LibreOffice Documentation Team Announces the LibreOffice Online Guide:
My experience working on this guide was fantastic, and I would urge anyone interested in getting involved with open source to consider documentation as a first step. The Document Foundation’s documentation team in particular has a very well-established process and infrastructure for producing their products, and one of the only things I can think of that would help them is more volunteers.
- From technical writer Shaloo in a blog post about the GenPipes project, Giving it your all to Documentation!
Unfortunately, most of us who write software, think that documentation means simply translating what the software does in plain English. That is so not true. Documentation is more to do with how to use your cool software and solve real life pain points. Staying in touch with your user needs is of paramount importance, whether it is code that you are writing or the documentation for using the same.
- From technical writer Laurel in a post on the Ensembl blog, Ensembl is part of the first Google Season of Docs!
It has been both fun and interesting to learn about the Ensembl REST API implementation as well as to learn about what people who use the REST API need to get started.
A brand new tutorial is now available for GDevelop, and we would like to thank @end3r for writing it as part of Google #SeasonOfDocs!
Thanks a lot to @felicity_brand for supporting the #OSGeoLive project in #SeasonsofDocs 2019. She did a great job and improved our @osgeolive documentation a lot.
- From technical writer Edidiong in the project report, Modernize (rewrite) the VLC user documentation:
Overall, It was one of the best things that happened to me this year. I have been using VLC for as long as I can remember and the fact that I was able to contribute to the organization is an honor.
- From technical writer Pavithra in the blog post, My GSoD Journey – Part 3:
I like working with the Wikimedia community. I got to interact with some really amazing folks and the overall experience has been wonderful! Even though Season of Docs has officially come to an end, I intend to continue contributing and would welcome interested folks to join us.
- From technical writer Mister Gold in the project writeup, Report for the Bot Docs project:
At the end of the GSoD program, my Rocket.Chat mentors asked me to review a technical writer job posting they’d created. They said that the contribution I made to Rocket.Chat is invaluable and cannot be underestimated. They were so excited and impressed by this project that they have decided to hire a person who will be in charge of all the qualitative documentation updates. Rocket.Chat team confirmed that this is one of the greatest achievements of all the times in Rocket.Chat thanks to my work.
- From technical writer Muhammad in the project report, OpenMRS: Write Code, Save lives!
GSoD not only provided me with an opportunity to learn about open source but also to interact with some of the most wonderful people around the globe working enthusiastically for betterment of society and help create and most importantly maintain a Medical Record System completely free of cost for under-privileged as well as other users.
GSoD not only increased my knowledge about open-source and led me to meet exciting people, it also helped me to further enhance my technical writing and managerial skills…
I would love to continue working for OpenMRS and be an active member of the community.
- From technical writer Areesha in a writeup of the project, OpenELIS documentation for end users:
Google Season of Docs introduced me to open-source community. I realized how open-source projects offer multiple benefits to its users. Open-source systems provide more flexibility, security and transparency to the users as the system is continuously being reviewed and updated…
Writing technical documentation for a system that is implemented at such a wide scale and is a part of a global community made me learn so much about how the technical documentation is done in the real-world at the corporate and professional level.
- From technical writer Anna in a writeup of the project, How did Open Collective’s docs change in three months?
This community has welcomed me with open arms and I couldn’t be more grateful for that. Open Collective has found in me a contributor for life, and I hope to keep contributing for as long as I can.
- From technical writer Anne in the project writeup, The Ultimate Beginner’s Guide to NumPy:
If you’re interested in getting involved with NumPy or Google Season of Docs, I highly recommend it. If you’re new to open source projects, you might have a bit of a learning curve setting up your workstation, becoming familiar with NumPy’s contribution guidelines, and getting to know the ins and outs of .rst and Sphinx, but it’s so worth it. It’s definitely challenging if you haven’t done it before, but keep going. Once you get those details nailed down, you can start having real fun!
- From technical writer Alex in a writeup of the project with International Neuroinformatics Coordinating Facility (INCF), Technical Writer, Google Season of Docs 2019:
I’M STILL SMILING!
It’s well worth taking a look at all the project reports listed on the Season of Docs website, to see the scope of the projects tackled, the challenges that the technical writers faced, and how they overcame them. Every story is different!
Please do let me know of any posts I’ve missed, or if you’d like to add any experiences of your own. Add a comment on this post so that others can read it too.
Opportunities to contribute to open source
If you’re looking for opportunities to contribute to open source, these opportunities abound.
A note to avoid potential confusion: Contributing to these projects would be outside of the Season of Docs program, unless you’re already officially signed up to take part in the relevant long-running project in Season of Docs 2019, or you’re accepted into a future Season of Docs program in 2020 or beyond.
Some suggestions for finding a project to contribute to:
- In their project reports listed on the Season of Docs website, many of the technical writers describe followup work to be done.
- The open source organisations published detailed lists of ideas in their original proposals for Season of Docs. Many of these ideas are not yet addressed, because Season of Docs is only three months’ worth of writing!
There are more Season of Docs 2019 results to come
To the technical writers and mentors working on the long-running projects for Season of Docs 2019: Have fun, best of luck with your projects, and I’m very much looking forward to seeing the results in February!
To add to the celebratory nature of this post, here’s a picture of a tea tree flower spray which I came across while walking in the Australian bush:
Last week Google announced a new program, Season of Docs (g.co/seasonofdocs). The program provides a framework for technical writers and open source organizations to work together on a specific documentation project chosen by the open source organization and the tech writer concerned. From April 2, interested open source organizations can start applying for this year’s Season of Docs. Exciting news indeed! But what happens before April 2? I decided to blog about some ways you can get started with Season of Docs right now.
Open source organizations can start planning the documentation projects they’d like help with, and letting technical writers know about those projects. Get the conversation going, and build up excitement amongst your open source community and amongst the technical writing community.
The first step is to think about a good project or projects that a technical writer can help you with. The Season of Docs website provides some generic ideas for doc projects. You should to craft a specific project or two, based on the actual doc needs of your project. Include links to the relevant docs or other resources within your open source repository or on your website. I’d recommend that you propose a a few different project types, because different tasks may be of interest to different tech writers. For example, you could offer one project to refactor your existing docs, another to create a specific tutorial, and so on.
Your goal is to attract tech writers by making them feel comfortable about approaching your organization and excited about what they can achieve in collaboration with your mentors during Season of Docs.
It’s a good idea to find out who in your community wants to be a mentor. The mentors don’t need to be tech writers. There’s help about the mentors’ role on the Season of Docs website too.
When you’ve gathered some project ideas, blog about the fact that your organization is putting forward an application to participate in Season of Docs. Use the blog post to tell tech writers about your ideas and ask for input. You don’t need to wait for applications to open. You can get a head start by kicking off the discussion now.
Use the tag #SeasonOfDocs when promoting your ideas on social media. To include the tech writing and open source communities, add #WriteTheDocs, #techcomm, #TechnicalWriting, and #OpenSource.
Exciting news: Google Open Source has announced a new program called Season of Docs. I’m excited because the goals of this program reflect two passions of mine: to help technical writers get started in the world of open source software, and to help open source projects build great documentation. I’m also excited because I’m on the program development team for Season of Docs.
Technical writers bring their documentation expertise to the open source project of their choice. In return, mentors from the open source organization help the technical writer gain an understanding of their open source community, processes, tools, and code.
A golden collaboration
When technical writers contribute to open source projects, both parties benefit. The open source project gains good documentation and improved contribution procedures. The technical writer gains experience in open source software, developer-focused products, new tools, and the ways in which open source communities work. A golden collaboration.
Open source is great. Some of the world’s most-used software is open source: the Linux operating system, Firefox web browser, LibreOffice, Apache web server, to name but a few well-known brands. Large companies like Microsoft, Google, Red Hat, and IBM contribute to, as well as use, open source code.
Open source ideology is great too. People share code in public repositories, collaborate on making the code better, invite others to join their communities… yet, all too often, people expect those newcomers to understand the product, the code, and the community’s values with very little good documentation.
Why the dearth of good docs? It’s clear from GitHub’s Open Source Survey that open source organizations know the value of good documentation, so why are there so many gaps? Because writing documentation is hard.
But wait… there are people who know how to do it well!
Many technical writers are keen to gain experience in developer-focused products such as APIs, SDKs, and various programming languages and tools. Technical writers look for opportunities to explore cloud computing, machine learning, hardware, and more.
When a technical writer wants to expand their resume or look for a new role, the advice is sometimes to build a portfolio by contributing to open source. But that’s not easy. There are so many open source projects out there. Where do you start? How can you be sure your contributions will be useful to the open source project? Who can help you understand the contribution procedures, the product, and the code?
Season of Docs gives technical writers and open source projects the opportunity to work together within a structured program.
Let’s go build great open source docs!
How does Season of Docs work?
First up, open source organizations apply to participate in Season of Docs. The list of accepted organizations is then published on the Season of Docs website, along with the ideas each organization has proposed for technical writing projects.
Then technical writers explore the list of participating open source organizations and their project ideas.
As a technical writer, you can decide which open source project you’d like to work with. It’s a good idea to get in touch with the open source organization to chat about their requirements and your own ideas. You can contact more than one organization if you like.
When you’re ready, you submit your application to participate in Season of Docs, including your project proposal and the name of the open source organization you’re interested in. You can submit more than one project proposal, but only one will be accepted.
If your technical writing project is accepted for Season of Docs, then you as a technical writer will work with your chosen open source organization for a few months (starting in September 2019) to complete your project. You work closely with your open source mentor for the duration of the program, to ensure successful completion of your project.
When can you start?
Open source organizations can start applying to participate in Season of Docs from April 2, 2019, and the website will show the list of participating organizations on April 30. Technical writers then have the opportunity to examine the list of participating open source organizations and explore the project ideas proposed by the organizations.
Technical writers can start applying to participate in Season of Docs from May 29, 2019.
The Season of Docs timeline shows the key dates and what happens in each phase of the program.
Want to learn more?
Take a look at the Season of Docs announcement on the Google Open Source Blog, or dive into the guides on the Season of Docs website at g.co/seasonofdocs. Join the mailing list at season-of-docs-announce to stay informed about when applications open and other important program events.
Google currently has an open role for a technical writer in the Sydney office. See the job posting. Here are a few thoughts, from me as a tech writer at Google in Sydney, on how you can prepare to apply for the role.
A note up front: These hints come from me personally, as a tech writer at Google. I’m not the hiring manager for the open role, and following these hints won’t assure you of a successful application.
The advertised role is for a technical writer in the software engineering area. Let’s dive straight in!
Resume, samples, writing exercises
For a tech writing application, the resume is super important. Treat your resume as the first writing sample you’ll submit to Google. Make sure it’s clear and consistent. For example, it doesn’t matter whether you use US, British, or Australian spelling, provided you stick to your choice throughout the document. The same applies to punctuation of bullet items—just be consistent. Avoid unnecessary capital letters, check your spelling… you know the drill.
If your resume shows the skills and experience that suit the role, Google will ask you to submit some writing samples and complete a set of writing exercises.
For the writing samples, make sure you send in the work that demonstrates sound tech writing principles. If you have any code that you’ve written and that you can link to from your resume (for example, on GitHub), that’d be useful too. Even if the code is something you put together while learning a programming language or experimenting with an API, that’s good.
You may be asked to complete some specific writing exercises. Take your time in completing the writing exercises. Apply your tech writing soft skills as well as standard tech writing principles. A good tip is to sleep on it before you submit the exercises. Come back the next day to take a fresh look at what you’ve written. Focus on the intended audience for each sample. Include comments noting any extra information you’d ask for if you were writing the docs in a real work environment.
Once your first interview has been scheduled, you’ll be able to chat to the Google hiring representatives and they’ll give you plenty of information about the interview process.
Usually there are a number of interviews, some by phone and some in person. You’ll speak to people in different roles, which may include tech writers, engineers, developer advocates, managers, and more.
A good hint for the interviews themselves is to remember you’re a tech writer, with the skills of a tech writer, and those skills are not the same as those of an engineer. Your interviewers may be tech writers, engineers, or managers. So, ask questions during the interview as if you were interviewing an engineer or a product manager. Make it clear to them that that’s what you’re doing.
You can find more tips to help you prepare on the Google Careers site.
It’s a good idea to become familiar with Google developer products, docs and style, to show your interest in the role. Be aware of the Google Developer Docs Style Guide, browse the Google Developer Docs site and the Google Cloud docs.
People often ask about the coding requirements for a tech writing role at Google. It’s a vexed question, and you’ll receive different replies depending on the role. This section of the post takes up a lot of space—arguably too much in proportion to its importance—but I’d like to give the best hints possible.
For this role the expectation is that you can comment on things like consistent and meaningful names for methods and classes, good use of code comments, and other aspects of code readability. In an interview, you should be able to ask the interviewer questions about a piece of code, as you would if you were planning to document it.
The job description mentions a few programming languages. It’s a good idea to focus on one (I’d recommend Python if you don’t already have a favourite) and do some studying in the leadup to the interview process. In fact, when I applied I continued studying throughout the process to keep the concepts and skills in focus. Life is busy, and it’s easy for some things to drop down into the less-easily accessible areas of our brains! This Python course is a good one.
To the best of my knowledge, you shouldn’t have to solve a problem in code during the interview. At most, you may be asked to write pseudo code. I’ve heard various reports about whether you need to do whiteboarding of simple code during an interview. I think it depends on the interviewer. I did have to do some whiteboard coding in one of my interviews, and I totally messed it up because I was extremely nervous. I still got the job. I did much better on the conceptual questions (what is a class, what is inheritance, what does “closure” mean to you, and so on).
For this particular role, we’re looking for someone who’s willing and able to continue learning about software and code. It’s not necessary to have in-depth coding skills. If during an interview you’re asked to do some coding that’s beyond your current skills, fall back to discussing the key technical concepts involved and to interviewing the interviewer about the requirements and goals of the application / system.
My top hints
Be passionate about tech writing. Let the interviewers see that you enjoy the role of tech writer, and be ready to tell them why. If you’re active in the tech writing community, let the interviewers know that. Mention any opportunities you’ve had to mentor other tech writers or students.
Be yourself. 🙂
Technical writers often need to create sample code, to illustrate the primary use case of an API or developer tool, and to help developers get started quickly in the use of the API or tool. Here are some tips on how to go about creating that code. I’ve jotted down everything I can think of. If you have more tips to add, please do. 🙂
I recently published a set of documentation on a utility library created by Chris Broadfoot, a Google developer programs engineer. The utility library is an adjunct to the Google Maps Android API. The documentation includes an overview of all the utilities in the library, a setup guide, and an in-depth guide to one of the utilities. (I’ll document more of the utilities as time goes on.) As part of the guide to the marker clustering utility, I created some sample code that illustrates the most basic usage of the utility and gets developers up and running fast.
Quick introduction to the API and the utility library
The Google Maps Android API is for developers who want to add a map to their Android apps. The API draws its data from the Google Maps database, handles the displaying of the map, and responds to gestures made by the user, such as zooming in and out of the map. You can also call API methods to add markers, rectangles and other polygons, segmented lines (called polylines), images (called ground overlays) and replacement map tiles (called tile overlays). It’s all in the API documentation.
The utility library is an extra set of code that developers can include in their Android apps. It includes a number of useful features that extend the base API. One of those features is “marker clustering”. The full list of features is in the utility library documentation.
The marker clustering utility
The sample code illustrates the marker clustering utility in Chris’s utility library. So before diving into the code, you be asking:
What’s “marker clustering”?
Let’s assume you have a map with a large number of markers. (Typically on a Google Map, a marker is one of those orange pointy droplets that marks a place on the map.) If you display all the markers at once and individually, the map looks ugly and is hard to grok, especially when the map is zoomed out and many markers are concentrated in a small area. One solution is to group neighbouring markers together into a single marker icon (a “cluster”) and then split them into individual marker icons when the user zooms out or clicks on the cluster icon. That’s what Chris‘s marker clustering utility does.
What does marker clustering look like? See the screenshots in the documentation.
Developers can implement the classes Chris has created and customise the appearance and behaviour of the clusters. The utility library also includes a demo app, containing sample implementations of the utilities.
The sample code
The best way to describe a code library is to provide sample code. I created a simple marker clustering example, based on the demo app. Take a look at the sample code in the documentation section on adding a simple marker clusterer.
Now compare it to the code in the demo app that’s part of the utility library: ClusteringDemoActivity.java
The differences, in a nutshell:
- The sample code doesn’t show any of the “plumbing”, such as the library import statements.
- The sample code does include a listing of both the primary method that does the clustering (called “
setUpClusterer()“) and a class that’s important for developers to understand (“
public class MyItem implements ClusterItem“).
- Instead of reading input from a file, the sample code includes a method called “
addItems()” to set up some sample data directly from within the code.
- I’ve added plentiful comments to the sample code, explaining the bits that are specific to marker clustering or the sample itself.
In summary, the sample code provides all the developer needs to get a simple marker clusterer working, just by copying and pasting the code into an existing Android project.
How to write sample code
While writing the sample code, a thought struck me:
Hey, it’s actually quite an interesting process writing sample code. I’ll blog about what I’m doing here, and see what other technical writers have to say about it. 🙂
First, a stab at defining the goals for the sample code:
- Get the developer up and running as quickly as possible.
- Be suitable for copying and pasting.
- Work (do what it’s meant to do) when dropped into a development project.
- Be as simple as clear as possible.
- Provide information that is not easy to find by reading the code.
- Illustrate the primary, basic use case of the API or tool.
And here are my jottings on how to go about creating a useful code sample:
- Find out what the primary and simplest use case is. That is what your code should illustrate. Talk to the engineers and product managers, read the requirements or design document, read the code comments.
- Find out what you can safely assume about your audience. Can you assume they are familiar with the technology you’re working with (in my case, Java and Android development)? Do you know which development tools they are using?
- Find some “real” code that does something similar to what you need. Perhaps a similar function or a working implementation that’s too complex for your needs.
- Simplify it. Make names more meaningful. Remove functionality that’s unique to your environment or that adds super-duper but superfluous features. Remove plumbing such as import statements and all but the essential error handling.
- Put your into a framework and test it. The framework should be one that your audience will be using. In my case, that’s an Android development project.
- Take screenshots of the code in action. They’re often useful to give people an idea of the goal of the sample code, and of what the API or tool can do.
- Get the code reviewed.
- Include it in the doc.
- If possible, put the code in a source repository and hook it up to some automated tests, to help ensure it will remain current.
- As far as possible, have all the necessary code in one piece, so that people can copy and paste easily. This may mean moving stuff around.
- Add code comments. Engineers often add technical comments to the code, but don’t include an introduction or conceptual overview of what’s going on. And our target audience, developers, will often read code comments where they don’t read other docs. So code comments are a great medium for technical communication!
Perhaps the most important thing to do is to see yourself as the advocate for or representative of those developers who need to use the API or tool you’re illustrating. Think what questions they would ask if they had access to the people and tools that you do, and put the answers into the documentation and sample code.
To do this job, tech writers need a certain level of coding knowledge, and also a good understanding of what a developer needs to get started. The sample code provides a stepping stone between the conceptual overviews and the complex implementations.
Well, that’s all I can think of. What have I forgotten? 🙂