Tag Archives: documentation

Season of Docs announces participating organizations

Season of Docs has announced the 50 participating open source organizations! You can view the list of participating organizations on the website.

Technical writer applications open on May 29, 2019 at 18:00 UTC. 

During the technical writer exploration phase, which runs from now until May 28, 2019, technical writers can explore the list of participating organizations and their project ideas. They should reach out to the organizations to gain a better understanding of the organizations and discuss project ideas before applying to Season of Docs.

For more information about the technical writer exploration phase, visit the technical writer guide on the website.

What is Season of Docs?

Documentation is essential to the adoption of open source projects as well as to the success of their communities. Season of Docs brings together technical writers and open source projects to foster collaboration and improve documentation in the open source space. You can find out more about the program on the introduction page of the website.

During the program, technical writers spend a few months working closely with an open source community. They bring their technical writing expertise to the project's documentation and, at the same time, learn about the open source project and new technologies.

The open source projects work with the technical writers to improve the project's documentation and processes. Together, they may choose to build a new documentation set, redesign the existing docs, or improve and document the project's contribution procedures and onboarding experience.

How do I take part in Season of Docs as a technical writer?

First, take a look at the technical writer guide on the website. The guide includes information on eligibility and the application process.

The technical writer exploration phase runs from April 30 - May 28, 2019. During this period, you can explore the list of participating organizations and their project ideas. When you find one or more projects that interest you, you should approach the relevant open source organization directly to discuss project ideas.

Then, read create a technical writing application and prepare your application materials. On May 29, 2019 at 18:00 UTC, Season of Docs will begin accepting technical writer applications and publish a link to the application form on the website. The deadline for technical writer applications is June 28, 2019 at 18:00 UTC.

Is there a stipend for participating technical writers?

Yes. There is an optional stipend that technical writers can request as part of their application. The stipend amount is calculated based on the technical writer's home location. See the technical writer stipends page for more information.

If you have any questions about the program, please email us at season-of-docs-support@googlegroups.com.

General timeline

  • April 30 - May 28: Technical writers explore the list of participating organizations and project ideas.
  • May 29 - June 28: Technical writers submit their proposals to Season of Docs. 
  • July 30: Google announces the accepted technical writer projects
  • August 1 - September 1: Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors.
  • September 2 - November 29: Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period.
  • December 10: Google publishes the list of successfully-completed projects.
See the full timeline for details, including the provision for projects that run longer than three months.

Care to join us?

Explore the Season of Docs website at g.co/seasonofdocs to learn more about participating in the program. Use our logo and other promotional resources to spread the word. Examine the timeline, check out the FAQ, and apply now!

By Andrew Chen, Google Open Source and Sarah Maddox, Google Technical Writer

Introducing Season of Docs

Google Open Source is delighted to announce Season of Docs, a new program which fosters the open source contributions of technical writers.

Season of Docs brings technical writers and open source projects together for a few months to work on open source documentation. 2019 is the first time we’re running this exciting new program.

Join us in making a substantive contribution to open source software development around the world.

Fostering collaboration between open source projects and technical writers

The Open Source Survey showed that documentation is highly valued in open source communities, yet there’s little good documentation out there. Why? Because creating documentation is hard. But...

There are people who know how to do docs well. Technical writers know how to structure a documentation site so that people can find and understand the content. They know how to write docs that fit the needs of their audience. Technical writers can also help optimize a community’s processes for open source contribution and on-boarding new contributors.

During Season of Docs, technical writers will spend a few months working closely with open source communities. Each writer works with their chosen open source project. The writers bring their expertise to the projects’ documentation while at the same time learning about open source and new technologies.

Mentors from participating open source organizations share knowledge of their communities’ processes and tools. Together the technical writers and mentors build a new doc set, improve the structure of the existing docs, develop a much-needed tutorial, or improve contribution processes and guides. See more ideas for technical writing projects.

By working together in Season of Docs we raise awareness of open source, of docs, and of technical writing.

How does it work?

  • April 2-23: Open source organizations apply to take part in Season of Docs
  • April 30: Google publishes the list of accepted mentoring organizations, along with their ideas for documentation projects
  • April 30 - June 28: Technical writers choose the project they’d like to work on and submit their proposals to Season of Docs 
  • July 30: Google announces the accepted technical writer projects
  • August 1 - September 1: Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors
  • September 2 - November 29: Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period
  • December 10: Google publishes the list of  successfully-completed projects.
See the timeline for details, including the provision for projects that run longer than three months.

Join us

Explore the Season of Docs website at g.co/seasonofdocs to learn more about participating in the program. Use our logo and other promotional resources to spread the word. Examine the timeline, check out the FAQ, and get ready to apply!

By Sarah Maddox, Google Technical Writer and Andrew Chen, Google Open Source

Building great open source documentation

When developers use, choose, and contribute to open source software, effective documentation can make all the difference between a positive experience or a negative experience.

In fact, a 2017 GitHub survey that “Incomplete or Confusing Documentation” is the top complaint about open source software, TechRepublic writes “Ask a developer what her primary gripes with open source are, and documentation gets top billing, and by a wide margin.”

Technical writers across Google are addressing this issue, starting with open source projects in Google Cloud. We'll be sharing what we learn along the way and are excited to offer this brief guide as a starting point.

Open source software documentation

Providing effective documentation for open source software can build strong, inclusive communities and increase the usage of your product. The same factors that encourage collaborative development in open source projects can have the same positive results with documentation. Open source software provides unique ways to create effective documentation.

When software is open sourced, users are regarded as contributors and can access the source code and the documentation. They’re encouraged to submit additions, fix code, report bugs, and update documentation. Having more contributors can increase the rate at which software and documentation evolve.


The best way to accelerate software adoption is to describe its benefits and demonstrate how to use it. The benefits of timely, effective, and accurate content are numerous. Because documentation can save enough time and money to pay for itself, it:
  • Helps to create inclusive communities
  • Makes for a better software product
  • Promotes product adoption 
  • Reduces cost of ownership
  • Reduces the user’s learning curve
  • Makes for happy users
  • Improves the user interface
When documentation is inadequate, the opposite can occur. Incorrect, old, or missing documentation can:
  • Waste time
  • Cause errors and destroy data
  • Turn away customers
  • Increase support costs
  • Shorten a product’s life span

Why supplying effective documentation can be such a challenge

Useful documentation takes time to write and must be updated with the software. Did the installation process change? Are there better ways to configure performance? Was the user interface modified? Were new features introduced? Updates like these must be explained to new and existing customers.

It’s not enough to add words to a file and call it documentation.

How many times have you tried to use documentation that was five years out-of-date? How long did it take you to find another solution? (Not long, right?) Using old documentation can be like hiking an overgrown trail. The prospects of rogue branches, poison ivy, and getting lost suggest you are unlikely to emerge unscathed.

At first blush, writing documentation may seem optional. However, as a developer, you can literally be so close to your product that you take its features and purpose for granted. But your customers have no idea what you know, or how to apply what you know to address their business challenges. And time is money.

Remember the swimmer who got halfway across the English Channel only to say, “I’m tired,” before turning around and swimming back to shore? Ignoring the need for documentation is like that. Developing a software product gets you some of the way to your goal whereas helpful documentation fulfills your goal.

Momentum matters a lot. If you can settle into a rhythm of implementing new features, fixing bugs in the code, as well as writing and updating documentation, you can propel yourself to success.

Create an inclusive open source community

In the same GitHub survey referenced above, 95% of the respondents were men but evidence suggests that clear documentation:
  • Can contribute to inclusive communities
  • Is more highly valued by those groups who are typically under-represented
Documentation that effectively explains a project's processes, such as contributing to guides and defining codes of conduct, is valued more by groups that are underrepresented in the open source community, such as women.

Factors that can lead to ineffective documentation

Conditions like these almost always compromise the quality of documentation:
  • Belief that it’s enough for open source software to just work.
  • Notion that a specification is as good as instructional text.
  • Idea that casual unreviewed contributions are sufficient.
  • Belief that unscheduled and unspecified software updates are acceptable.
  • Minimal to no style guidelines.

Conquer your documentation challenges

Use these best practices to provide helpful and timely documentation:

1. Identify common terminology

Define and influence the usage and adoption of terminology for your open source project. Use the same terminology in the guides and in the product. Involving a writer early in product development can lead to a natural synergy between the user interface, guides, and training materials.

With clear definitions of terms and consistent usage in the documentation, you can teach your community to speak a common language. As a result, everyone in your products’ ecosystem can communicate more effectively with each other.

2. Provide contribution guidelines

Opensource.com describes exactly why contribution guidelines are so important. Consider how Kubernetes describes the types of documentation contributions your users can make and how to make them.

3. Create a documentation template

To make sure your contributors provide details in a consistent format, consider providing a document template to capture details for common topics such as:
  • Overview
  • Prerequisites
  • Procedural steps
  • What’s next

4. Document new and updated features

When a feature is added or updated, ask that it be documented. You can even provide guidelines to capture key information. Initially, some may think it cumbersome to require that  instructions be provided early in the development process. However, think of documentation to be like testing in that nobody really wants to do it but things work so much better. Sufficient testing and teaching are good for quality and momentum.

Code reviewers and maintainers of open source software have power. Code reviewers can (and should) withhold approval until documentation is sufficient.

Remember, not all changes require documentation updates. Here’s a good rule of thumb:

If an update to a project will require users to change their behavior, then documentation updates may be required.

If not, how will your customers find the new feature you worked so hard to implement? Said another way, if a change doesn't require tests, it probably doesn't require docs, either. Use your best judgement. For example, code refactoring and experimental tweaks need not be tested or documented.

As always, simplify and automate this process as much as possible. At Google, teams can enforce a presubmit check that either looks for a flag that indicates a doc update isn't necessary (presubmit checks for style issues can prevent a lot of arguments, too). We also allow owners of a file to submit changes without a review.

If your team balks at this requirement, remind them that simple project documentation is about sharing the information you have in your head so that many others can access it later without bothering you.

Documentation updates aren't typically onerous! The size of your documentation change scales with the size of your pull request (PR). If your PR contains a thousand lines of code, you may need to write a few hundred lines of documentation. If the PR contains a one-line change, you may need to change a word or two.

Finally, remember that documentation needn’t be perfect, but instead fit for use. What's most important is that key information is clearly conveyed.

5. Conduct regular freshness reviews

At least every quarter, review and update your content. Many hands make for many voices, many typos, and many inconsistencies. Don’t let content persist unchecked for years without periodically confirming it’s still useful.

In conclusion, success breeds success. By effectively documenting open source software, everybody wins.

We hope you'll put this guidance to work and help your open source project become even more successful! We'd love to hear from you if you do, or if you have questions or useful advice to share.

By Janet Davies, Google OpenDocs

Making the Google Developers Documentation Style Guide Public

Cross-posted on the Google Developers Blog

You can now use our developer-documentation style guide for open source documentation projects.

For some years now, our technical writers at Google have used an internal-only editorial style guide for most of our developer documentation. In order to better support external contributors to our open source projects, such as Kubernetes, AMP, or Dart, and to allow for more consistency across developer documentation, we're now making that style guide public.

If you contribute documentation to projects like those, you now have direct access to useful guidance about voice, tone, word choice, and other style considerations. It can be useful for general issues, like reminders to use second person, present tense, active voice, and the serial comma; it can also be great for checking very specific issues, like whether to write "app" or "application" when you want to be consistent with the Google Developers style.

The style guide is a reference document, so instead of reading through it in linear order, you can use it to look things up as needed. For matters of punctuation, grammar, and formatting, you can do a search-in-page to find items like "Commas," "Lists," and "Link text" in the left nav. For specific terms and phrases, you can look at the word list.

Keep an eye on the guide's release notes page for updates and developments, and send us your comments and suggestions via the Send Feedback link on each page of the guide—we want to hear from you as we continue to evolve the style guide.

Posted by Jed Hartman, Technical Writer

Making the Google Developers documentation style guide public

Posted by Jed Hartman, Technical Writer

You can now use our developer-documentation style guide for open source documentation projects.

For some years now, our technical writers at Google have used an internal-only editorial style guide for most of our developer documentation. In order to better support external contributors to our open source projects, such as Kubernetes, AMP, or Dart, and to allow for more consistency across developer documentation, we're now making that style guide public.

If you contribute documentation to projects like those, you now have direct access to useful guidance about voice, tone, word choice, and other style considerations. It can be useful for general issues, like reminders to use second person, present tense, active voice, and the serial comma; it can also be great for checking very specific issues, like whether to write "app" or "application" when you want to be consistent with the Google Developers style.

The style guide is a reference document, so instead of reading through it in linear order, you can use it to look things up as needed. For matters of punctuation, grammar, and formatting, you can do a search-in-page to find items like "Commas," "Lists," and "Link text" in the left nav. For specific terms and phrases, you can look at the word list.

Keep an eye on the guide's release notes pagefor updates and developments, and send us your comments and suggestions via the Send Feedback link on each page of the guide—we want to hear from you as we continue to evolve the style guide.

Java 8 Language Features Support Update

Posted by James Lau, Product Manager

Yesterday, we released Android Studio 2.4 Preview 6. Java 8 language features are now supported by the Android build system in the javac/dx compilation path. Android Studio's Gradle plugin now desugars Java 8 class files to Java 7-compatible class files, so you can use lambdas, method references and other features of Java 8.

For those of you who tried the Jack compiler, we now support the same set of Java 8 language features but with faster build speed. You can use Java 8 language features together with tools that rely on bytecode, including Instant Run. Using libraries written with Java 8 is also supported.

We first added Java 8 desugaring in Android Studio 2.4 Preview 4. Preview 6 includes important bug fixes related to Java 8 language features support. Many of these fixes were made in response to bug reports you filed. We really appreciate your help in improving Android development tools for the community!

It's easy to try using Java 8 language features in your Android project. Just download Android Studio 2.4 Preview 6, and update your project's target and source compatibility to Java version 1.8. You can find more information in our preview documentation.

Happy lambda'ing!

A New Issue Tracker for our AOSP Developers

Posted by Sandie Gong, Developer Relations Program Manager & Chris Iremonger, Android Technical Program Manager

Like many other issue trackers at Google, we're upgrading our Android Open Source Project (AOSP) issue tracking system to Issue Tracker. We are hoping to facilitate a better collaboration between our developers and our Android product teams by using a tool we use internally at Google to track bugs and feature requests during product development.

Starting today, all issues formerly at code.google.com/p/android/issues will migrate to Issue Tracker under the Android Public Tracker component. You may have noticed that we are already using the new tool to collect feedback on the O Developer Preview!

What has been migrated

Getting started with Issue Tracker


You can learn more about navigating our Issue Tracker from our developer documentation. By default, Issue Tracker displays only the issues assigned to you. You can easily change that to show a hotlist of your choice, a bookmark group, or a saved search. You can also adjust notification settings by clicking the gear icon in the top right corner and selecting Settings.

The mappings in Issue Tracker are also slightly different than code.google.com so make sure to check out Life of a Bug to learn more about what the various statuses mean.



Searching for component specific issues


Opening a code.google.com issue link will automatically redirect you to the new system. We've cleaned up some of the spam, but you'll be able to find all of the other issues from code.google.com in Issue Tracker, including any issue you've reported, commented on, or starred.

You can view all reported Android issues in the Android Public Tracker component and drill down to see reported issues for specific categories of issues, such as Tools and Support Libraries, by searching for specific components.

Filing a bug or feature request

Before filing a new issue, please check if it is already reported in the issues list. Let us know what issues are important to you by starring an existing issue.

Submitting a new issue is easy. Once you click "Create Issue", search for the appropriate component for your issue. Alternatively, you can just follow the correct issue creation link for each component listed in Report Bugs.

Here's some helpful links to get you started!


Topic
Relevant Links
Navigating and creating issues in the Android component
Navigating Google Issue Tracker
Google Issue Tracker announcements for other products