開発チームにスタイルガイドとドキュメント生成ソフトウェアを導入する際の落とし穴は何でしょうか？
会社のiOSアプリのドキュメントを作成するために、Objective-Cコードドキュメントの生成に使用するDoxygenのフレーバーである appledoc の使用を検討しています。サーバーがコミット後のフックでドキュメントを生成し、内部ネットワークでドキュメントを公開するという考え方です。
現在、コード自体のコメントも含めて、どのような種類のドキュメントもほとんどないので、コードを作成するときに、さらにドキュメントを書き始めるように人々に依頼する必要があると思います。この流れで、私はチームと協力して、Objective-Cコードの「スタイルガイド」（ Google's など）を作成します。これにより、記述と文書化の方法に関するいくつかの基本ルールが規定されます。コード。
上記の計画の潜在的な落とし穴は何ですか？スタイルガイドは効果的ですか？コーディング標準を採用することには利点がありますが、開発者はそれを制限していると思いますか？そして、このようなドキュメンテーションプロジェクトは機能しますか？そうでなければ、なぜ彼らは失敗するのですか？
（Stack Overflowに数回投稿して中程度の成功を収めましたが、ここに投稿するのはこれが初めてです。質問を改善できるかどうか教えてください。ありがとうございます！）
プロセスと文化の観点から注意を払うべき要素：
1。ドキュメントの内容がどうあるべきかについての期待が適切に設定されていることを確認しますドキュメントが作成されたときに書かれると予想されるwhatを定義することが重要です。多くの場合、それは驚くべきことですが、人々は内部の仮定をします。役に立たないコメントは、コメントがないのと同じくらい悪いです。
2。 API固有のドキュメントは、通常、すべてではありません
ほとんどの場合、API固有のドキュメントは、ブラックボックスモジュール間の統合に最適であり、複雑なシステムの進化に合わせて統合できます。ただし、全体的なアーキテクチャ、詳細設計またはモジュール設計、アルゴリズム、機能、ビジネスルールなどのドキュメントの重要な要素に代わるものではありません。
3。強制する前に、人々がバイインすることを確認してください。
どのプロセスでも真の成功は、それを達成するための人々からのコミットメントがある場合にのみ達成されます。それを方針として宣言することは可能かもしれませんし、人々はそれのために逐語的に従うかもしれませんが、それが正しい精神で行われない限り、それは実を結ぶことはありません。
4。正確な基準を凍結する前に、人々の関与と合意を取ります
麦粒腫のコーディングは常に役立ちます。そして誰もそれを否定しません。ただし、個人的に従うこととポリシーの内容に違いがある場合は、変更が必要です。したがって、ほとんどの人がすでに何に適合しているかを確認し、被害が最も少ないルールを定義するのが最善です。また、委員会が課した規則よりも、変更を受け入れる可能性が高いと多数派が考えているために特定のコーディングガイドラインが選択されたことがわかった場合。
5。監視と適応
それが始まる初日には完璧なものはありません。あなたが何を期待していたかについてのいくつかの基本的な期待を保ち、物事がそのように起こっているかどうかを追跡します。物事が追跡されない場合、最初の良い成功でさえ消えていきます。
**詳細 これを参照
@Dipanの答えは要点をカバーしていますが、この種の文化的変化には、小さなことから始めて実験する必要があることがあります。非常に小さなプロジェクトから始めます。あなたがすでにあなたの側にいる人々との1つ。ドキュメントを作成したり、ドキュメントツールを使用したり、より一般的には新しいことを試したりするのが好きな人。彼らにプロセスをデバッグさせ、フィードバックを書くように依頼します。 2〜3人のプログラマーと協力して何かができたら、変更を加えることができます。
時間がかかる場合がありますが、ニーズを正確に定義し、プロジェクトが環境にうまく適合するかどうかを判断するために必要です（ツールのセットアップと管理は簡単ですか？人々は本当にドキュメントを使用していますか？作成のプロセスはありますか？ドキュメントは、人々がアイデアを策定するのに役立ちますか？他のチームにドキュメントにアクセスしてもらいたいですか？など）
予算があれば作家を雇います。私たちはプログラミングライターと呼ばれ、プロジェクトの所有権を引き継ぐことができます。 Androidの仕事をしていて、同様の問題を抱えているシアトル地域の会社と仕事をしています。スタイルガイドは悪い考えではありませんが、良いドキュメントの具体例を示すことを強くお勧めします。また、フィードバックを軽く踏みます。ネガティブフィードバックが多すぎると、模範的ではないライティングスキルを公開することをすでに躊躇している人を思いとどまらせるだけです。
ダグ