タグ付けされた質問 「documentation」

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 6年前に閉鎖されました。 目標は、次の主要な要件を備えたオンラインドキュメントシステムを用意することです。 主に、すべてのアプリケーションの最終的な技術文書の中間段階として使用されます（ただし、おそらく完了しません）。通常は次のように使用されます。誰かに問題があり、それを修正し、修正をすぐに書き留めます。今起こっているのは管理不能なことです。誰かに問題があり、私はそれを修正します。私も誰かも喜んでいますが、2か月後、他の誰かが同じ問題を抱えています。 どこからでもアクセスでき、Apacheサーバーの背後で実行されます ユーザー/グループ管理、読み取り専用/読み取り/書き込み/管理アクセスを許可 形式はそれほど重要ではありません：プレーンテキストでもかまいませんが、wikiスタイルの方がいいでしょう 安いか無料 私のいくつかのアイデア： ファイル共有上またはsshを介してファイルを提供するだけです（短所：Windowsとあまり互換性がない、長所：シンプル、任意のファイルタイプが可能） SCMに保存します（svn / git、上記と同じですが、アクセスとアクセスの制御が簡単です） Confluence：既にJiraを使用していますが、Confluenceには価値がありますか？Jiraとどのように統合されますか？ 他に何か？ これらについてコメントすることをorしないでください。他のシステムと経験を共有してください。

11 documentation 

DRY Principle（Do n't Repeat Yourself）は、「すべての知識は、システム内で単一の明確な権威ある表現を持たなければならない」と述べています。ほとんどの場合、これはコードを指しますが、多くの場合、ドキュメントにも拡張されます。 すべてのソフトウェアシステムには、選択したかどうかに関係なくアーキテクチャがあると言われています。つまり、構築するソフトウェアには構造があり、その「構築された」構造がソフトウェアのアーキテクチャです。 構築されたソフトウェアシステムにはアーキテクチャが付属しているため、そのシステムのアーキテクチャ記述を作成することはDRY原則に違反していますか？ 結局のところ、アーキテクチャを知る必要がある場合は、常にコードを見ることができます...

11 agile  documentation  architecture  dry 

現在のところ、この質問はQ＆A形式には適していません。回答は事実、参考文献、または専門知識によってサポートされると予想されますが、この質問は議論、議論、世論調査、または広範な議論を求める可能性があります。この質問を改善し、場合によっては再開できると思われる場合は、ヘルプセンターをご覧ください。 7年前に閉鎖されました。 プロジェクト提案を起草するとき、標準テンプレートを使用しますか？ どの機能/情報を含める必要がありますか？含めて良かったのは何ですか？どんな種類のボイラープレート情報を押し込むべきですか？ 設計パターンやコンセプトは特に役立ちますか？

11 project-management  business  management  documentation 

私たちのソフトウェアには、リフレクションを介して動的に検出されるいくつかのクラスがあります。すべてのクラスには、リフレクションコードがオブジェクトをインスタンス化する特定のシグネチャを持つコンストラクターがあります。 ただし、誰かがメソッドが参照されているかどうか（Visual Studio Code Lensなどを介して）を確認すると、リフレクションを介した参照はカウントされません。人々はそれらの参照を見逃し、明らかに未使用のメソッドを削除（または変更）することができます。 リフレクションを介して呼び出されるメソッドをマーク/ドキュメント化するにはどうすればよいですか？ 理想的には、メソッドは、同僚とVisual Studio / Roslynおよび他の自動化ツールの両方が、メソッドがリフレクションを介して呼び出されることが意図されていることを「確認」するような方法でマークする必要があります。 使用できる2つのオプションを知っていますが、どちらも十分に満足できるものではありません。Visual Studioは参照を見つけることができないので： カスタム属性を使用して、この属性でコンストラクタをマークします。 問題は、Attributeプロパティをメソッド参照にすることはできないため、コンストラクターは参照が0と表示されることです。 カスタム属性に慣れていない同僚はおそらくそれを無視するでしょう。 私の現在のアプローチの利点は、リフレクションパーツが属性を使用して、呼び出すコンストラクターを見つけることができることです。 コメントを使用して、メソッド/コンストラクターがリフレクションを介して呼び出されることを意図していることを文書化します。 自動化ツールはコメントを無視します（同僚もそうするかもしれません）。 XMLドキュメントコメントは、 Visual Studioがメソッド/コンストラクタへの追加の参照をカウント持つように使用することができます させるMyPluginそのコンストラクタ反射を経由して起動するためのクラスです。呼び出しリフレクションコードが、intパラメーターを受け取るコンストラクターを検索するとします。次のドキュメントでは、そのコードlensに、1つの参照を持つコンストラクターを示しています。 /// <see cref="MyPlugin.MyPlugin(int)"/> is invoked via reflection より良いオプションはどれですか？ リフレクションを介して呼び出されることを意図したメソッド/コンストラクターをマークするためのベストプラクティスは何ですか？

11 c#  .net  documentation  reflection 

私の意見では、単体テストケース自体がコードのドキュメントとして機能します。私の会社では、単体テストケースの上に詳細なjava docコメントを書いてほしいと思っています。そうする必要がありますか？そんなコメントはありますか？

11 unit-testing  documentation 

自分用に小さなスクリプトを作成しているときは、コードをコメントでスタックします（コードよりもコメントが多い場合があります）。私が話している人の多くは、これらのスクリプトは個人的なものであっても、文書化する必要があると言っています。しかし、コメントはドキュメントの形式ではありませんか？ これではないでしょう： $foo = "bar"; # this is a comment print $foo; # this prints "bar" 特に開発者が私のコードを使用している場合、ドキュメントと見なされますか？または、ドキュメントはコード自体の外にあると見なされますか？

11 documentation  comments 

私はプロジェクトの唯一の開発者です。これは、他のソフトウェアプロジェクトと同様に、将来誰かに奪われる可能性があります。 機能Aを実装するためにパターンXを使用したとしましょう。機能を開発して完成させた後、今学んだパターンYを使用して同じ機能を実装できることに気付きました。しかし、機能Aはうまく機能しており、XからYへのリファクタリングは時間がかかり、ほとんどメリットがありません。 次に、機能Bを実装します。これはAに似ていますが、今回はこの機会にパターンYで遊んでみたいと思います。機能Aを実行するときよりも、最終結果に満足しています。ただし、コードでは2つ使用していますXとYの異なるパターン。 ただし、機能AIを構築するときに機能Bと同じパターンを使用するのに十分なスキルがなかったという事実を除いて、異なるパターンを使用する実際の理由はありません。 この質問は、特定の問題に適切なパターンを選択することに関するものではないことに注意してください。同様の問題を解決するためにコードベースに共存する約2つのパターンは、リファクタリングするのに十分な時間を与えると1つに減らすことができます。 そのコードは臭いですか？ このようにソースコードを保持することの欠点は何ですか？ 1つのパターンのみを使用する必要がありますか？つまり、Bを記述するときに、AをリファクタリングしてYを使用するか、Xを使用し続けるか。 ソースで、類似した機能に2つの異なるパターンがある理由は本質的に理由がないことをどのように伝えることができますか？ 次の開発者が私のコードをどう思うかについてあまり心配していませんか？

10 design-patterns  refactoring  documentation 

外部の開発者が使用している商用ライブラリとコード例を作成します。ライブラリの使用方法を広範囲に説明する（登録済みユーザーは利用できますが、閉鎖された）ドキュメントがあります。 開発者の多くは初めてのユーザーなので、多くの初歩的なエラーが発生します。 エラーログにドキュメントへのリンクを含めることは適切ですか？考えられる欠点は何ですか？いくつかは予想できますが、以下を克服することは可能と思われます ドキュメントのURLが古い 最新のドキュメントに反映されていないバージョン固有のエラー 他に何か問題があり、無関係なドキュメントに送信することで開発者の時間を無駄にしています 意味の例の下に、太字のテキストを追加するのは良い考えですか？ [エラー]プロジェクトstandalone-pomで目標org.apache.maven.plugins：maven-archetype-plugin：1.2.3：generate（default-cli）を実行できませんでした：目的のアーキタイプが存在しません（com.example.library。 archetypes：library-archetype-blank：1.2.3.0）->詳細および考えられるトラブルシューティングについては、http：//example.com/docs/setting-up-an-archetypeを参照してください

10 documentation  api-design  error-handling  error-messages 

私はアマチュア開発者であり、これまでのすべてのプログラムは、コード内に文書化できるほど単純でした。コードを読んでいる間、私が何をしているのか、そのようなアクションは明らかでした（私の標準的なテストは、6か月後にコードを見て、最初に読んだときにすべてを理解することでした-私は短いメモリスパンを持っています）。 私は今、プログラム間のさまざまな相互作用を覚える能力を超えてプログラムに直面しています。 コード自体 データベース内のインデックス さまざまなモジュール間の相互作用（「ワーカー」コアコードと「ライブラリ」モジュール） 私の現在のドキュメントはホワイトボードで、コード、データベースインデックス、実行中のアクション、状態変化などを指すあらゆる種類のボックスと矢印があります。参考までに、混乱の断片： 私の質問は、より複雑な製品のドキュメント化のための標準または名前付きのベストプラクティスのセット（これは特定の名前でグループ化された一連のプラクティスであるという意味で名前が付けられている）があるかどうかです。 私が探す必要があるキーワードは何ですか（「ドキュメントソフトウェアアーキテクチャ標準」での一般的な試みと同様のバリエーションは、通常、ワークフローまたはビルディングアーキテクチャCADシステム用のソフトウェアにつながりました）。 また、高レベルの説明には一般的なベストプラクティスがなく、誰もが独自の哲学を構築することも期待しています。

10 architecture  documentation 

github READMEにどのような情報が表示されると思いますか？ すべてをREADMEに入れますか？すなわち 前書き 取り付け バージョン ユーザーガイド 実装 テスト中 関連資料 または、README（紹介、インストール、バージョン）に特定のものを入れて、他の情報をGithub wikiに配置するのが最適でしょうか。

10 documentation  github 

私はかつて、ドキュメントにXMLコメントを要求するファンでした。それ以来、私は2つの主な理由で考えを変えました。 優れたコードのように、メソッドは自明でなければなりません。 実際には、ほとんどのXMLコメントは無意味なノイズであり、付加価値はありません。 多くの場合、GhostDocを使用して一般的なコメントを生成しますが、これは役に立たないノイズとは次のことを意味します。 /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } 私には、それは明白です。とはいえ、含める特別な指示がある場合は、XMLコメントを絶対に使用する必要があります。 私はこの記事からのこの抜粋が好きです： 時々、あなたはコメントを書く必要があるでしょう。しかし、それは規則ではなく例外であるべきです。コメントは、コードでは表現できないものを表現している場合にのみ使用してください。エレガントなコードを記述したい場合は、コメントを削除し、代わりに自己文書化コードを記述してください。 コードがそれ自体で説明するのに十分でない場合にのみXMLコメントを使用すべきだと思うのは間違っていますか？ これは、XMLコメントによってかなりのコードが見苦しく見える好例です。それはこのようなクラスを取ります... public class RawMaterialLabel : EntityBase { public long Id { get; set; } …

10 .net  programming-practices  development-process  documentation  comments 

現在、私の現在のプロジェクトではアジャイルメソッドを使用しており、次のような大量のストーリーがあります。 アシスタントとして、お客様に払い戻しを請求し、リクエスト時にお金をもらうことができるようにしたい 顧客として、私はアイテムを受け取ることができるように購入の代金を支払いたいです。 これまでに行った方法は、すべてのスプリントで最も重要なストーリーを選択し、それをいくつかの正式な要件仕様にまとめます（同じ仕様で似ているストーリーのいくつかをグループ化します）。ストーリーによっては、画面上のボタンまたはワークフロー全体の場合もあります。 問題は、ストーリーが多すぎるため、システムのどの部分にストーリーが関連しているかがすぐには明らかにならないことです。 それは開発者の時に機能し、すべてのスプリントは開発者が何をする必要があるか、そして彼らが行う必要がある変更を概説するスペックを取得します。しかし、このストーリーリストの維持とテストに関しては、バグの追跡が非常に難しくなり、一般的には仕様のみを維持することになります。これは、画面の機能の一部がさまざまな場所で文書化されているためです。ストーリーで分割。 ストーリーに基づいた仕様を書くことは良い考えですか？ストーリーを間違った方法で書きましたか？

10 agile  documentation  requirements  user-story 

私が現在取り組んでいる一般的なアプローチは- ドキュメントをできるだけ避けます 別のチームが必要とする場合のみ文書化する 明確にするために、私はコードドキュメントを意味するのではなく、これは私たちが行うことです。つまり、UMLまたはDBスキーマ、クラス図、仕様などのワードドキュメントの場合、設計プロセスを取り巻くすべてのドキュメントを意味します。 文書化しない上司の理由を挙げます。 時間がかかります-実装に集中してください 設計が変更された場合-ドキュメントは変更され、二重の問題が発生します 結局、誰も読みたくない何百ものページを取得し、誰も実際には編集しないので、いつかは古くなるでしょう その痛み-誰も本当にそれをしたくない 今では作業が速くなることに気づきましたが、何も理解せずに、ここに行って古いコードに直接飛び込んだ時間も覚えています。 実際、私はまだこの古いコードのほとんどを取得していません。場合によっては、さまざまな開発者からの多くのパッチが小さな調整を試みているのを目にすることがあります。 ドキュメント化の欠如は、この種のパッチと広義のシステム理解の欠如を助長すると思います。 私の質問は： チーム間で継続的な知識を促進しながら、迅速かつ効率的になるように、ドキュメントをどのようにバランスさせることができますか？

10 documentation 

休業。この質問には、より焦点を当てる必要があります。現在、回答を受け付けていません。 この質問を改善してみませんか？質問を更新して、この投稿を編集するだけで1つの問題に焦点を当てます。 5年前休業。 私が現在所属しているチームはかなりの離職率を経験しており、メンバーは通常、同じ会社内の異なるプロジェクトに移動しています。現在、新しいメンバーの「トレーニング」は、彼らを実際の経験を提供し、より新しい採用者がメンターに何か尋ねるかどうかより多くの上級開発者に尋ねる主要な連絡先（通常はトレーニングを完了する最も最近の人）とペアにすることです知りません。これは、新規採用者が迅速に関与する機会を提供し、メンターにシステムへの理解を向上させることも要求します。 しかし、ご想像のとおり、このスタイルのトレーニングは非常に時間がかかり、十分な知識の伝達にはなりません（誤解が広まり、ギャップが拡大します）。 私は、将来の新入社員向けのドキュメントとトレーニング資料の生成を任されています。私はすでにテクニカルライティングを時々行っていますが、それはエンドユーザー向けであり、非常に具体的であり、多くのスクリーンショットがあり、完了するまでに長い時間がかかります。 新入社員向けの新しいドキュメントを作成することは優先度が低いと考えられており、私は現在、約40時間しか作業できません。私が技術文書を書いている現在の方法でシステムを文書化しても、40時間でかろうじて表面を傷つけるだけです。特に、コードベースだけでなく、展開とサポートについても文書化する必要があることを考慮します。 ドキュメントの作成に多大な時間を費やすことなく、ドキュメントをすばやく作成して、新入社員をできるだけ早く最新の状態にするにはどうすればよいですか？ 追加情報： 現在、Wikiといくつかのトレーニングドキュメントがありますが、どちらもまばらです。

10 documentation  training 

私は適切に文書化されたコードの支持者であり、そのコードの考えられる欠点をよく知っています。それはこの質問の範囲外です。 Visual StudioのIntelliSenseがどれだけ好きかを考慮して、すべてのパブリックメンバーにXMLコメントを追加するというルールに従うのが好きです。 ただし、冗長性には1つの形式があり、私のような過度のコメンターでさえも気になります。例として、List.Exists（）を取ります。 /// <summary> /// Determines whether the List<T> contains elements /// that match the conditions defined by the specified predicate. /// </summary> /// <returns> /// true if the List<T> contains one or more elements that match the /// conditions defined by the specified predicate; otherwise, false. /// …

10 documentation  comments  intellisense