Google Season of Docs 2021 Volunteering Proposal

Google Season of Docs 2021 Volunteering Proposal

Personal Information

• Technical writer: Simin Liao
• Academic Background: BA from National Taiwan University
• Current job: Technical Writer
• Location: Taiwan (GMT +08:00)
• Language: English, Chinese

Abstract

User documentation is one of the ways that introduces users to its functions. If the documentation is complete and well-constructed, discrepancy between users and developers will reduced significantly. The users will be more easily to use the software, its functions and be able to resolve the common issues themselves. They would not need to ask questions frequently.

A complete and clear user documentation could benefit the organization in several ways. First, it increases users— interest to use the software. As we all know, the beginning of doing anything is always the hardest, with clear instruction at hands, a user could break into the field more smoothly and will be less likely to give up during the process. Second, it reduces cost of managing questions that are frequently asked and could focus on more productive feedback in the community. Last but not least, it serves as an icon of the product and the development team. A well-constructed documentation demonstrates that it has a well-organized development team.

Professional Background

I am a full-time in-house technical writer from an International company. For documentation, I am trained in two ways: to use simple words and to write for novice. It may be a common myth that we should use the most accurate and the most beautiful words to write the steps, but we forget that most of the users are ESL (English as Second Language) speakers. Instead of writing an essay, the most important thing for a documentation is to deliver the correct instructions to the users. That includes not using the words that are too uncommon and rare. My company follows the rules of Simplified Technical English (ASD-STE100), so I am very familiar with the level of English words and I know which are more appropriate than others for non-native speakers. In addition, in order to eliminate ambiguity, I am also trained to use specific user-friendly syntax, which is based on the feedback of our internal experienced technical writers and documentation users.

On the other hand, writing for novice is one of the things that is often ignored by many people. In my previous experience working with engineers, since they are already very experienced and familiar with the process, they often jump too fast. One of my job is to slow them down, break their ideas down into small steps and explain the specific terms.

Apart from in-job trainings, I also studied technical writing reference guide from Google, Microsoft and some parts of Red Hat. I acquired their writing style and will apply to this project.

I hold a bachelor degree in linguistics and literature from National Taiwan University. Throughout four-year training, I was immersed in words and sentences that I have written many term papers about semantics and syntax. My academic practice gave me an advantage of working with people from engineering background. A great development team is always consists of smart engineers, and I am the one who captures their fabulous ideas, in a simple and transferable way. This is my calling.

Current Issue

Tutorials are not properly structured

At the beginning when I was trying to find out how to use Wechaty and where to start, it took me a very long time. I found that the pages are not really consistent to each other. For example, if the the information in this page is not what I was looking for, I would have problem getting to the correct location. Furthermore, normally when the users are looking for tutorials, they sometimes could not fully explain their questions and were trying to seek for some possible solutions. Even worse, if they are looking for some specific functions and they could not get answers from the handbook, they would tend to think that Wechaty is not comprehensive and does not meet their needs.

Information is scattering

Currently there are four ways we could find information about this project: tutorial, video, GitHub or in the Wechaty community. They are not properly linked or labeled, so once the users need some help, they needs to go back and forth in the four places, which is very time-consuming and the users may give up during the process.

Information is not sufficient

In the community, we could see many people asking simply questions everyday. The main reason is because the users cannot find the answer they need. The documentation is not comprehensive and does not cover the topic. Besides, no one is maintaining the Frequently Asked Questions, so the current tutorial is always outdated.

Syntax is not consistent

This is kind of the hardest part for the ESL speakers. The user documentation is maintained by too many people, with different writing styles and different writing tone. Unlike writing essays, we ought to eliminate personal style in writing and create a consistent standard that everyone should follow.

Approach

I believe that Wechaty already have many great developers contributing to your project. The biggest problem right now is that all the documentation are independent. Instead of looking for another developer to flourish the documentation, doing the things that you could actually do it yourself, what Wechaty really need now is an experienced technical writer who could make a concrete structure for the documentation. In short, Wechaty needs the foundation first, before adding more cool functions or user interfaces. In the future, since there will definitely be more people contributing to this project, with a well-constructed structure, they could more easily allocate their new documents and the development team could organize the tutorials more comfortable.

Responsibilties

As a full time technical writer working with various engineers from different fields, I play an important role in editing the document and coordinating projects. These two are the things that are often ignored when it comes to technical writing, but are actually very crucial to whether the documentation is complete and professional or not.

Through my previous on-job and personal training, I will commit in the following two areas:

1. Edit and proofread the documentation

• Make sure all the documents follow Google Developer Documentation Style Guide, including format, syntax and word choice.
• Make sure the technical instruction is understandable for a novice. ( I will follow the instructions step by step as if I’m a user to make sure that the document is easy to understand and doable.)
• Make sure all the document structures are consistent.
• Make sure the language (English) is simple for ESL (English as Second Language) speakers to comprehend.
• Edit the documents and review PRs within three days after receiving.

2. Manage each documents

• Make sure that every writer follows the document release schedule and report to Huan if anyone is failling behind.
• Make sure that every writer knows the rules of Wechaty documentation.
• Collaborate with another volunteer and writers for document release.

Proposed Budget

$500