Announcing Docsy: A Website Theme for Technical Documentation

Have you ever struggled with the process of creating documentation for an open source project? Do you have an open source project that's outgrown its README? Open source projects need great docs to succeed, but great open source doc sites aren't always easy to produce and share.

Google supports over 2000 open source projects, and there has been growing demand from these projects for tooling and guidance to help them write and publish their documentation. To meet this need we created Docsy: a documentation website with templates and guidance for documentation, which we’re open sourcing to the public to use and help improve the tool.

Docsy builds on existing open source tools, like Hugo, and our experience with open source docs, providing a fast and easy way to stand up an OSS documentation website with features specifically designed to support technical documentation. Special features include everything from site navigation to multi-language support – with easy site deployment options provided by Hugo. We also created guidance on how to add additional pages, structure your documentation, and accept community contributions, all with the goal of letting you focus on creating great content.

Who’s using it?

The Kubeflow, Knative, and Agones websites were built using the Docsy theme, with more projects in the pipeline. We’ve also created an example site that uses lots of Docsy features for you to explore and copy.

Ready to get started?

Visit the Docsy site to find out how to create your first site with Docsy! You can either use Docsy like a regular Hugo theme, or clone our example site. Docsy is an open source project—of course—and we welcome your issues, suggestions, and contributions!

Come Meet the Google Open Source Team at OSCON!

Google Cloud is proud to be a Diamond Sponsor at OSCON, and we’re excited for another year of connecting, learning, and sharing with the open source community! Google is deeply grateful to all of your amazing open source efforts, so to celebrate, our booth will have an Open Gratitude wall where we will acknowledge your contributions, and where we encourage you to express your gratitude for those who have helped you in open source!

Once you’ve recognized your open source heroes on the Open Gratitude wall, stick around at the Google Open Source booth to learn about topics such as open source governance, documentation, open source in ML and gaming, encouraging non-code contributions, and about Google’s open source outreach programs in general. At our booth sessions you can also explore open source projects such as Kubernetes, Istio, Go, and Beam (as well as other Apache projects). Booth office hours run from 10:15am to 7pm Wednesday, July 17, and from 10:15am to 4:10pm on Thursday, July 18. The full schedule will be posted at the booth—please come by and check it out!

In addition to the events at the booth, the Google open source team has two workshops on Tuesday, July 16:

• 9:00 –12:30: Zero to Docs: Hands-On Documentation Workshop

This half-day workshop kicks off with an overview of research-backed documentation best practices. Andrew Chen, Erin McKean, and Aizhamal Nurmamat kyzy lead you through a hands-on exercise in which you'll create the skeleton of a ready-to-deploy documentation website for your open source project.

• 1:30 – 5:00: Hands-on Kubernetes New Contributor Workshop

Paris Pittman takes you through the ins and outs of the Kubernetes contributor community so you can land your first PR. You'll learn about SIGs, the GitHub workflow, its automation and continuous integration (CI), setting up your dev environment, and much more. Stick around until the end, and you'll have time to work on your first PR with the help of current contributors.

We also hope you attend the main conference sessions presented by Googlers, especially the keynotes on Wednesday (Built to last: What Google and Microsoft have learned growing open source communities) and Thursday (Be a Docs Star), and the sessions on Wednesday:

• 11:00 – 11:40: Live coding a machine learning model from scratch
• 1:45 – 2:25: Flutter meets the Physical World
• 1:45 – 2:25: Introducing Kubeflow w/ Special Guests Tensorflow & cross-cloud machine learning
• 4:15 – 4:55: Real-time streaming APIs: from data-center to Internet clients

And Thursday:

• 11:50 – 12:30: Open Source Citizenship
• 1:45 – 2:25: CI/CD in a cloud native world
• 2:35 – 3:15:Break me if you can: practical guide to building fault-tolerant systems
• 2:35 – 3:15: Serverless On Your Own Terms using Knative
• 4:15 – 4:55: Code Generation: Principles and Challenges

As part of our commitment to creating a diverse and inclusive community, we’ve redirected our conference swag budget into diversity scholarships. (We believe you’d prefer to have more interesting conversations with a wider range of people over another pair of socks!) But if you are looking for a souvenir of your time in Portland there will be a special Portland-themed sticker featuring Pancakes, the (extremely adorable) gRPC mascot, and we encourage projects to take and leave stickers in our sticker-swap space!

OSCON is one of the highlights of the year for those of us who love open source—we’re thrilled to be able to share what we’ve learned with you, and to learn what you’re interested in and excited about (and also what you think could improve). See you in Portland!

Truth 1.0: Fluent Assertions for Java and Android Tests

Software testing is important—and sometimes frustrating. The frustration can come from working on innately hard domains, like concurrency, but too often it comes from a thousand small cuts:

assertEquals("Message has been sent", getString(notification, EXTRA_BIG_TEXT)); assertTrue(     getString(notification, EXTRA_TEXT)         .contains("Kurt Kluever <kak@google.com>"));

The two assertions above test almost the same thing, but they are structured differently. The difference in structure makes it hard to identify the difference in what's being tested.

A better way to structure these assertions is to use a fluent API:

assertThat(getString(notification, EXTRA_BIG_TEXT))     .isEqualTo("Message has been sent"); assertThat(getString(notification, EXTRA_TEXT))     .contains("Kurt Kluever <kak@google.com>");

A fluent API naturally leads to other advantages:

• IDE autocompletion can suggest assertions that fit the value under test, including rich operations like containsExactly(permission.SEND_SMS, permission.READ_SMS).
• Failure messages can include the value under test and the expected result. Contrast this with the assertTrue call above, which lacks a failure message entirely.

Google's fluent assertion library for Java and Android is Truth. We're happy to announce that we've released Truth 1.0, which stabilizes our API after years of fine-tuning.

Truth started in 2011 as a Googler's personal open source project. Later, it was donated back to Google and cultivated by the Java Core Libraries team, the people who bring you Guava.

You might already be familiar with assertion libraries like Hamcrest and AssertJ, which provide similar features. We've designed Truth to have a simpler API and more readable failure messages. For example, here's a failure message from AssertJ:

java.lang.AssertionError: Expecting:   <[year: 2019 month: 7 day: 15 ]> to contain exactly in any order:   <[year: 2019 month: 6 day: 30 ]> elements not found:   <[year: 2019 month: 6 day: 30 ]> and elements not expected:   <[year: 2019 month: 7 day: 15 ]>

And here's the equivalent message from Truth:

value of:     iterable.onlyElement() expected:     year: 2019     month: 6     day: 30 but was:     year: 2019     month: 7     day: 15

For more details, read our comparison of the libraries, and try Truth for yourself.

Also, if you're developing for Android, try AndroidX Test. It includes Truth extensions that make assertions even easier to write and failure messages even clearer:

assertThat(notification).extras().string(EXTRA_BIG_TEXT)     .isEqualTo("Message has been sent"); assertThat(notification).extras().string(EXTRA_TEXT)     .contains("Kurt Kluever <kak@google.com>");

Coming soon: Kotlin users of Truth can look forward to Kotlin-specific enhancements.

By Chris Povirk, Java Core Libraries