ドキュメントでより良い英語を書いて、レビューして、指導するにはどうすればよいですか？
私の仕事は、世界中に広がっている強いアメリカの会社で、他の開発者のみが直面する内部システムのドキュメントで、英語の散文を（プルリクエストの形式で）書いて確認することを定期的に含みます。
その記述は、ドキュメントWebサイトとAPIのドキュメントスニペット（たとえば、REST APIのSwaggerドキュメント）の2つのカテゴリに分類されます。これらの両方がユーザーの初期に大きな影響を与えると思います私たちのシステム/製品の印象、そしてその最初の印象は私にとって重要です私たちはチームに正式なテクニカルライターを置いていません。
私はネイティブの英語を話す人で、学校では英語でOKをしました。私のチームの半分以上は英語を母国語とする人ではありません。明らかに、彼らの英語は他の言語での私のスキルよりもはるかに優れています。
しかし、私はしばしば、ネイティブスピーカーを含め、ドキュメントに表示される英語の品質にがっかりします。静的分析、ベストプラクティス、チームガイドライン、経験則、個人的な経験を利用して、コードをレビューするのはとても快適です。私はドキュメントの変更をレビューすることにあまり慣れていません-基準点や信頼できる具体的な証拠がないと感じています。学校からずっと使ってきた直感だけです。私はよく正当な理由や論理なしで、私がテキストについてあるべきだと思うものでPRにコメントすることになります。
悪い日には、自分の文章に疑問を投げかけます。誰も私の英語にコメントすることはないので、私のコードのように定期的なフィードバックは得られません。また、自分の書いたものが確実にわからない場合は、後輩の開発者にそれらを改善するよう指導するべきではないと感じます。
プログラミング言語とコンパイラーの快適性と安全性だけに欠けているのか、あるいはここに改善の余地があるのかはわかりません。自分が書いたもの、ドキュメントについての建設的な批判、そして最終的にはチーム全体をどのように改善できますか？
「プログラマーの語彙」を改善し、プログラミングの概念を正式に議論することを容易にするいくつかのリソースをおそらく見つけたでしょう。たとえば、あまりにも多くを行うクラスについてすでに直感を持っているかもしれません。次に、単一責任の原則について読み、それが概念を心に具体化するのに役立ちました。
他のほとんどのクリエイティブドメインには同様のリソースがあります。書くために、正規の Strunk＆White のようなスタイルガイドがその役割を果たします。それはあなたが書くことについての具体的なルールを詳しく説明しているだけで、直感的に感じるかもしれません。それはあなたがあなたが見逃していると感じる正当化を提供するのに役立ちます。
私はあなたの苦痛を感じます、コーディングが得意な人を見つけるのは時々困難ですおよび（彼らが母国語でドキュメンテーションを書く必要がある場合でも）適切なライティングスキルを持っています。
誰かのライティングスキルを向上させるには何年もかかります。したがって、これをバランスさせるために私が知っている唯一の方法は、文章を書くのが上手な人（コーダーである必要はない）を見つけ、定期的にドキュメントをレビューするタスクを明示的に与えることです。組織内に誰かがいるかもしれませんし、外部から誰かを雇う必要があるかもしれません。
（個人的な注意：私が英語を話しているわけではないので、ネイティブスピーカーがすぐに目にするタイプミスや文法の問題を見落としていることが多いので、誰かがここで私の回答の誤りを訂正するときはいつでもとても幸せです。 ）
ソフトウェア開発では、 ペアプログラミング の慣習があります。ここでは、2人の開発者が一緒にプログラミングを行い、特に「あなたはどうしますか」と「なぜこのようにしたのか」という質問をして、お互いから学びます。
pair-documentationのようなことをネイティブスピーキングの専門家と一緒にやらせていただければ幸いです。
アプリやウェブサイトを他の言語にローカライズするのに役立つウェブサイトで、ネイティブドイツ人として、私がアプリの英語の翻訳に基づいて自分のドイツ語の文言を修正しているのを見るのは興味深いことでした。これは、私がより良いドイツの技術文書を書くことを学ぶのに貴重でした。 （より良い=文法エラーが少なく、非技術用語を理解しやすい）
誰も私の英語にコメントしないので、定期的なフィードバックは得られません
これがあなたの問題です。フィードバックを必要としないほど上手に英語を話す人はいません。
誰か、誰でも見つけて、あなたが書いたものを彼らにレビューしてもらいます。彼らがそれについて言うことと彼らがどれだけよく理解するかに注意を払います。
これを待たないでください。手を伸ばして助けを求めましょう。よくやる。メモを求めて私の机に20ページを落とさないでください。あなたが書くように私をあなたのプロセスの一部にしてください。私に尋ねるだけではいけません。他の人にも聞いてください。
これを行うと、すぐに人々はあなたがフィードバックを望んでいることに気づき、それを提供する用意があるでしょう。