Knative elects new Technical Oversight Committee members

Towards the end of 2019, Knative project initiated a series of changes to its governance to ensure sustainability in the long term. Over the last week, the project reached a new milestone by successfully wrapping up its first Technical Oversight Committee (TOC) elections, bringing more vendor diversity to the technical stewardship of Knative.

Google has grown thousands of open source projects throughout the years, and it is this collective knowledge that informed the changes proposed to Knative governance. Over the last six months, we worked together with the other members of the Knative Steering Committee, and with the project’s contributors to create a clear set of rules for technical leadership and governance, describing the many ways in which contributors could engage with the project. This process was key to developing trust with Knative’s community, the project’s most valued stakeholder. In the exercise of this vote, the community was able to test the new election process, which proved to be solid: it will be repeated annually for this project, and can serve as a model for other projects as well.

The TOC election, which had a turnout of 70% of active contributors to the project, yielded a new technical stewardship for Knative, with members representing RedHat, VMWare and Google, as follows:

Nghia Tran (Google) - new member
Markus Thömmes (Red Hat) - new member
Grant Rodgers (Google) - new member
Matt Moore (VMWare) - existing member
Evan Anderson (VMWare) - existing member

Members of Knative TOC not only have the technical stewardship of the project in their hands for the next two years, they also model the community’s values: they have strong technical skills, they contribute to the project, and they are collegial, mentoring other contributors and helping the project to grow in a sustainable and healthy way.

We celebrated this important milestone for Knative at the last community meetup. Watch the video to meet the new TOC members, and check out the contribution guidelines to join the project.

By María Cruz, Google Open Source

SoD: experiences and tips for participation

Have you ever heard about a program that lets technical writers contribute to open source documentation? Towards this effort, Google launched its pilot program for Season of Docs (SoD) around April 2019. SoD immediately caught my attention because it is the first-ever program that seamlessly brings tech writing to the open source world. By carefully selecting open source organizations and their projects, SoD allows seasoned or aspiring technical writers around the world to work closely with an open source organization, and understand their open source product, processes, and tools.

Luckily, I discovered SoD 2019, submitted my application—and after being selected to work for Tor—started my journey into the world of open source. I successfully completed my project in March 2020, and my project report was called out on the Results page for SoD 2019 that lists all successful contributions.

Now in its second year, SoD has gained momentum and is the talk of most technical writing communities and student circles. For the benefit of SoD aspirants, I am recounting my participation experiences along with useful tips in this blog post. I have included answers to questions that I am frequently asked, along with some simple tips to help you successfully complete your project.

• Firstly, all aspiring participants for SoD 2020 must go through the program and its timeline hosted on the Season of Docs website. Make sure you read the Technical writer guide to understand the different phases of the program.
• It’s a common myth that only seasoned technical writers who have coding knowledge are at fit for this program as SoD 2019 saw a lot of students participating in the program. Experienced technical writers or even students, who can show their interest in tech documentation are free to participate. From the highly to moderately technical projects available, you can opt for a project depending on your expertise and knowledge.
• During the application phase, try to shortlist organizations closest to your domain knowledge and work area, and submit project proposals for two or three organizations. This increases your chance of being accepted by an organization. I shortlisted Tor and Hydra because of my interest in anonymous communications and my experience of working with APIs.
• Before submitting your proposal, it’s a good idea to establish interaction with the org mentors to understand if you’re going in the right direction with your project proposal and most importantly to break the ice for future communications. I found some interesting project ideas and reached out to the mentors to understand their expectations of the project before submitting my application. In hindsight, this proved to be extremely valuable, as I was able to fine-tune my proposal in collaboration with my mentor, and I had already built a rapport with them.
• Build your project proposal based on whether you’re opting for a three- or a five-month program. Break down details by months and weeks, which will testify your commitment to the project. I had chosen a standard three-month long project and detailed my work by months. When scoping your project, always allow time for roadblocks and unforeseen situations.
• After your proposal is selected by an organization, it’s community-bonding time. Take this phase seriously and use this time to get to know your peers in the organization, build a rapport with your mentors, set up a communication channel with them, and prepare your work environment. My project proposal for Tor was accepted, and my mentors reached out to me to quickly get me up-to-speed with their communication tools, meeting timings, and smoothly inducted me into the networking team that I was going to work with. Even before I started working on the project, I was attending their weekly meetings and learning more about the work they do.
• During the doc development phase, try to accomplish everything you promised in your proposal. At the same time, don’t feel bogged down by any changes that arise due to the complexity of your proposal. I faced hiccups during this phase because some of my ideas were not possible to implement and I had to rescope my proposal. Thanks to the invaluable support from my mentors and my peers at Tor, I was able to overcome all the obstacles and move forward with my project. The key to overcoming hurdles during your project is to keep your mentors updated about your work with frequent communication.
• Once the work’s done complete your project report which will serve as the final assessment. Ensure that this report clearly shows all the work you’ve done; nothing is too big or too small to highlight in this report. A well-written report is more important than your project proposal as this decides whether your project has been successful. Based on this report, your mentor gives you a pass or fail mark for your project.
• If your project is successful, you receive a stipend at the end of the program if you opted for one. Choosing to opt out of the stipend does not increase your chances of being selected to the program. This depends solely on your project proposal and your efforts at bonding with the chosen communities before applying.

For any more questions or concerns that you may have at any point in the program, I’d suggest looking up the FAQ for technical writers. You can also give a shout out to the extremely helpful program admins at season-of-docs-support@googlegroups.com.

I hope I have inspired SoD 2020 applicants to make their participation successful. I wish each one the very best.

By Swati Thacker, guest writer from Oracle

Insights from mixing writers with open source

The OSGeo Foundation participated in Google’s first Season of Docs, where Google sponsored technical writers to contribute to open source projects. The Open Geospatial Foundation (OSGeo), is an umbrella organization for around 50 geospatial open source projects. I’ve contributed to a number of these projects over the years and co-mentored the two Season of Docs technical writers allocated to us.

Screenshot from the OSGeoLive distribution we've been documenting, available under a CC-By license.

During our involvement we discovered that, like many open source projects, we knew little about:

• The state of our docs.
• What we were aiming for.
• What our priorities were.
• The details of the challenges we faced.
• How to improve.

We learned:

• How hard it is to keep tech docs current.
• Skillsets from multiple roles are needed to create good docs.
• Open source’s docs and writing processes are immature when compared to software development.

It is an exciting problem space with high-value challenges ready to be tackled. It reminds me of the early days of open source before it became trendy with business.

What should tech writers work on?

Open source communities welcomed the chance to have tech writers improve our docs, and expressed a pressing need for it, but found it challenging to articulate what exactly needed fixing.

• People explained that their project docs often hadn’t been updated between doc releases.
• Some projects had noticed new features that had not been documented.
• Other projects had issue lists—collating observed deficiencies—but had no systematic review.
• Most observed that docs were created by developers with no formal tech writing training.
• Many noted that docs written by non-native language speakers and would benefit from grammatical review.

But where should we start? We needed to decide on what we wanted, what we should work on first.

What’s the definition of good docs?

And then we realized that we didn’t have a good definition of “good documentation.” For our software projects, we have a comprehensive incubation process to assess the maturity of software and the project’s community, but we couldn’t find a similar set of metrics to define “good documentation.” So we started TheGoodDocsProject, to collate “best-practice templates and writing instructions for documenting open source software.” This helped us define what we were aiming for, and prioritize what we can achieve with our available resources.

Documentation audit

Once we knew what good docs looked like, we were then able to audit the status of project’s docs:

• What documentation do we have?
• Does it cover all the functionality?
• Does it cover end-user needs?
• Is the documentation any good?

We discovered that the quality, currency, and completeness of our OSGeo docs were immature when compared to the quality software they described.

It takes a village to raise good docs

In researching open source projects’ documentation needs, it’s become clear that crafting good docs requires multiple skillsets. Ideally, a doc team would have access to:

• A developer with a deep understanding of the software being described.
• A software user who’s able to explain the application within the context of the application’s domain.
• An educator who understands the principles of learning.
• An information architect who understands how to structure material.
• A writer who writes clearly and concisely with good grammar.
• A translator who can translate docs into multiple languages.
• A DevOps person who can set up doc build pipelines.
• A community builder, facilitator, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas collaborate together.

Technical writers usually have a high-level understanding of most of these domains and their skills are often under-appreciated and under-utilized, especially if directed with a vague “just clean up the grammar and stuff”. The best docs typically have been influenced by multiple stakeholders, which can be partly achieved using templates to collaborate between domains, timeframes, projects and organizations.

Tools for documenting open source projects are painful

We experienced significant difficulties trying to convert between writing and software toolsets. We love the versioning of git, are frustrated by clunky Markdown interfaces, and want access to editing and review workflows of Word and Google docs, along with grammar and syntax plugin tools such as Grammarly. Translation tools such as Transifex are pretty cool, too.

If a project were to address this use case, it would be an awesome gift to the open source community. Having someone write an application which addresses this use case would be helpful. Maybe there is an idea in here for a future Google Summer of Code?

Achievements during OSGeo’s Season of Docs

We’re quite proud of our achievements during OSGeo’s participation in the Season of Docs. Our allocated tech writers have amplified the effectiveness of our existing documentation communities, and our documentation communities have amplified the effectiveness of these tech writers.

• Felicity Brand worked with around 50 of OSGeo’s open source projects to update their Quickstarts as part of our OSGeoLive distribution of software.
• Swapnil Ogale worked directly with GeoNetwork’s documentation team, auditing the breadth of docs, and their quality, setting up templates for future docs to work towards, and updating a number of the docs.

Further:

• We kicked off TheGoodDocsProject—“Best practice templates and writing instructions for documenting open source software.”
• In conjunction with the OGC and ISO spatial standards communities, we kicked off an OSGeo Lexicon project, to coordinate official definitions for terminology used within the OSGeo context. This will apply best practice definitions to prior haphazard glossaries.
• We did a deep-dive analysis of the documentation challenges faced by QGIS, one of OSGeo’s most successful projects. Surprisingly, their biggest problem isn’t a lack of tech writers or complicated tools (although they are factors). The key problems center around:
• Poorly capturing community goodwill and offers of assistance.
• A lack of direction.
• Struggling to keep up with a rapidly evolving software baseline.
• Insufficient writing expertise.
• A high technical barrier to entry.
• Documentation and training being generated outside of the core project.
• Awkward documentation tools and processes.

Season of Docs 2020

Does tech writing interest you? If so, check the Season of Docs projects for 2020 and consider taking part.

By Cameron Shorter, Google technical writer and geospatial open source developer