These 7 suggestions summarized by senior technical translators will double the efficiency of PR after reading

War Code Pioneer, the second phase of the PR solicitation order (hereinafter referred to as "War Code Pioneer") is in full swing, involving OpenAtom OpenHarmony (hereinafter referred to as "OpenHarmony") main warehouse, SIG warehouse, and tripartite warehouses, a total of 1000+ code warehouses. You challenge.
Friends who have just seen the event must have a question: What kind of business background can participate in the Battle Code Pioneer event? Is it possible to find some basic ways to raise PR? To this end, we invited King He, a contributor to the first phase of Battle Code Pioneer and one of the captains of the second phase, to bring us some of his effective experience. Below is his sharing.
Practice has proved that people from different backgrounds are helpful to fully identify problems. If you are a translator, although you do not necessarily have deep technical knowledge, you can use your professional skills to help people find language problems in the project. In the same way, the same is true for colleagues with testing, data, and legal backgrounds. The participation of people with different expertise is more conducive to fully discovering various types of problems. This is similar to a fully functional team in agile development. Participate in roles more comprehensively and identify problems more fully. Heroes do not ask where they come from, as long as they dare to challenge, they can participate in the battle code pioneer and contribute to open source projects.
This article is based on the perspective of a technical translator. From the perspective of developer experience, we will discuss common data problems in code files with you, and share some personal suggestions on this basis. The article is mainly divided into three parts: the significance of data content to the developer ecology; typical problems affecting data experience; some initiatives to improve data experience.

First of all, you need to briefly understand the significance of the data content to the developer ecosystem.
According to the status quo of the developer ecology and open source ecological reports in recent years, complete and accurate content is one of the important factors for developers to choose an ecology. According to Accenture's survey report, developers believe that technically accurate and up-to-date content are the two most important elements in the developer ecosystem.

Source: ENGAGING THE DEVELOPER COMMUNITY - What Developer Ecosystems Need to Know, Accenture
The 2021 China Open Source Developer Report jointly released by OSCHINA and Gitee further supports this point. It can be seen from the report that the importance of the abundance of relevant documents/materials is second only to the quality of the source code.

--Excerpted from "2021 China Open Source Developer Report"
Good information is better than thousands of horses, and the importance of information is self-evident. A good horse is equipped with a good saddle, and a good code must have good data matching, so as to produce the effect of 1+1 greater than 2, to help developers get started better, produce a good developer experience, and attract more developers to participate. A complex technical product, if there is no manual, the user cannot use the product efficiently and correctly. Code is like a complex product. Without complete information, developers will not be able to understand the function and implementation mechanism of the source code, which will greatly affect their experience.
For the OpenHarmony open source project, the text content mainly includes two parts: one is the documents published in the Docs warehouse, including but not limited to development guides, API references, etc. The second is the various descriptive information contained in the code warehouse, such as readme, code comments, log logs, API descriptions, etc.

So, what are the factors that affect the quality of developer experience data content?
According to developer ecology related reports, these elements include but are not limited to: accuracy, completeness, currency, findability, and readability. It should be noted that most of the previous reports took mainstream open source projects as the basic research objects. These projects are mainly dominated by top players in Europe and the United States. They have natural advantages in language and culture, and have good internationalization and localization maturity. Therefore, aspects such as internationalization, localization, and basic language quality also require the OpenHarmony open source project to focus on.
Next, for the English text content, what are the typical issues that can be paid attention to in the Battle Code Pioneer event? This time, we mainly use the text problem of non-Docs warehouse as an example.
Special statement: The following examples are for illustrative purposes only for technical communication, and do not constitute any express or implied statement or statement. At the same time, due to the continuous changes and updates of the relevant warehouse contents, if there is any discrepancy, please refer to the actual situation.

1. Accurate and clear <br>Example 1: The words are not expressive. The API here is DelUser, and its function is to delete a user, so the description should be Delete a user instead of user authentication.

Example 2: The meaning is wrong. PIN_MIXED is Mixed PIN authentication, and FACE_2D is 2D face recognition authentication.

Example 3: The meaning is opposite. Here is the callback of the inactive state, superimposing syntax errors, increasing the difficulty of understanding. The actual meaning should be: Callback invoked in the main thread when an ability becomes inactive.

2. The content is complete <br>According to the requirements of open source, the content of comments in the open source code warehouse must be in English. Limited by the ability of English expression or internal compliance considerations, developers may be inclined to delete or give up some necessary content that needs to be translated into English, such as a brief description of the document, implementation mechanism or attention, etc., as shown in the following example: Left The side enum lacks necessary annotations, and developers cannot understand the difference between short period, normal period and long period.

3. Reasonable organization <br>The organization of information should conform to the logical cognitive sequence of users. For example, API introduction should follow the information organization structure of "API function description + permission + parameter description + return description". In the following example, the API name is directly replaced by the API function description, and the actual API function description appears after the permission.

The reference is modified as follows:

4. Consistency <br>Consistency is mainly reflected in two aspects: style consistency and content consistency.
Example 1: Inconsistent expression style. In the following log description, the upper and lower case styles of the upper and lower lines are inconsistent:

Example 2: The content does not match the actual. In the following Readme, the code warehouse name in the directory structure does not match the actual code warehouse name:

5. Basic language problems <br>Example 1: Spelling errors appear in comment statements or API names, parameters, etc., as shown in the following example: misspelling is wrong, the correct one should be failed.

Let's look at another special case. Although pin is not misspelled, it is actually the abbreviation PIN of personal identification number. If it is written as pin, the meaning is completely different.

Example 2: Grammar errors and irregular expressions are common in code files, as shown in the following example: The upper and lower sentences are inconsistent in style. start device find for restart does not use sentence caps, the first letter of the first word is capitalized. There are grammatical errors in both sentences, and because of improper word usage, the internal logical relationship between the two sentences is not reflected. The front indicates the action: Start discovery of devices for restart. The latter indicates the action result: Failed to start device discovery.

Let's look at another example, where Active and Deactive are adjectives and cannot be used in place of verbs. The corresponding verbs should be Activate and Deactivate.

6. Layout Problems <br>Excessive width of single-line content, or improper line breaks will cause unsightly layouts. As shown in the following example, the sentence is improperly broken, and the content of the following line can be moved to the upper line:

amend as below:

7. Inclusive <br>Inclusive language is an important trend today. The use of unbiased and inclusive language is an important reflection of brand temperature in cultural compliance and humane care. Some previously accepted terms were gradually replaced, such as chairman, aldermen implying male dominance, especially when addressing women. The following example expression violates the requirements of roles and labels in inclusive language, and parent should be used instead of father:

There are other aspects that deserve our attention, such as the careful use of terms that define class and race. For example, the current practice of the industry and friends is to replace master and slave with primary and secondary respectively, and replace blacklist and whitelist with trustlist and blocklist, respectively.
The above are some examples of problems that affect language and cultural experience. We can pay more attention to this type of problems in the war code activities.

Some initiatives to improve the data experience <br>A successful ecosystem cannot be separated from the ultimate developer experience. Bugs, big or small, can have varying degrees of negative impact on the developer experience. I take this opportunity to call on everyone to:
• Changing mindsets: Developer profiles are a key part of the developer journey and play an important role in the developer experience. For open source projects, high-quality materials are the basis for developers to contribute. Product features and data, like the two ends of a balance, should be given equal attention.
• User Perspective: The developer is the first reader and user of the material. In the war code activities, we can find out the accuracy, completeness, clarity and other aspects that affect the developer's task completion based on the developer's perspective, and actively raise issues and PRs to jointly improve the quality of the data.
• Low-level mistakes: Some low-level mistakes do not necessarily prevent users from understanding and completing tasks, but they can certainly negatively affect the brand's reputation. We should try our best to find and correct such problems, and jointly defend OpenHarmony's quality reputation.

Welcome interested developers and friends to participate in the battle code pioneer, PR solicitation order! Submit PR in Gitee's OpenHarmony code warehouse to participate in activities, and build a prosperous OpenHarmony ecosystem with developers around the world! Open Gitee now and submit PR for OpenHarmony. Your small step is a big step for OpenHarmony's open source.
We are a group of people doing a great thing together. Only by working together to build the ultimate developer experience in our respective areas of expertise can we help the OpenHarmony ecosystem to grow steadily and far, and we will jointly witness OpenHarmony becoming a leader in the Internet of Everything era. Pearl.
A few years later, when we look back on this history, we can proudly say to our children with the open source contributor certificate that behind this great ecology lies our hard work and dedication, which is so fascinating. proud.