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

私は現在、設計ドキュメントを更新して、将来の開発者向けに正しく最新のものにするためのプロセスを進めています。 現在、ドキュメントは事実のみに焦点を当てており、設計がどのようになっているかを示しています。提示された決定の根拠はありません。理論的根拠を把握することが重要だと思います。そうすることで、開発者は何かがそうである理由を知ることができます。すべての設計上の決定、特にプロジェクトに取りかかる前に下した決定に関するすべての理論的根拠を追加することはできませんが、この部門でできることをやっています。 ただし、いくつかの設計上の決定は、プロジェクトの要件を考えると、敬意を表して非常に貧弱な決定です。ただし、良いものもいくつかあります。 私の最初の考えは、将来のメンテナーの注意を集めるために、設計上の問題と潜在的な解決策またはこれらの問題の回避策についての議論を含めるべきだということでしたが、設計文書がこの種の議論と情報の場所であるかどうかはわかりません。他の人がこのシステムで作業し、ドキュメントを更新するので、デザインの「批評」が「このデザインを新しいものに引き裂く」ように雪だるまして欲しくありません。これは明らかに不適切です。 私のマネージャーがどちらの決定も支持するので、それは私次第です。私が取るアプローチに関係なく、作成されたドキュメントは公式にバージョン管理され、通常は開発作業を任される前にシステムで作業する開発者に提供されます。新しい開発者は、開発作業を開始する前に、特定のソフトウェアシステムに関連するドキュメントに慣れることが期待されています。 質問： 設計文書が未加工の事実（「これが設計」）と論理的根拠（「これが設計である理由」）に固執するか、設計上の問題となる可能性のある欠陥のない問題を指摘するために使用されるべきか将来の開発者？ 設計ドキュメントを使用してこの情報をキャプチャする必要がない場合、どのタイプのドキュメントでそれをキャプチャする必要があり、その他は設計合理性、トレードオフ、および既知の問題（欠陥ではないため、欠陥を追跡するための議論）でキャプチャする必要があります他のツールを使用していますか？）

13 design  documentation 

エンティティ、ビジネスロジック、およびデータアクセスクラスの有益なクラスドキュメント形式を探しています。 ここから次の2つの形式が見つかりました フォーマット1 ///----------------------------------------------------------------- /// Namespace: <Class Namespace> /// Class: <Class Name> /// Description: <Description> /// Author: <Author> Date: <DateTime> /// Notes: <Notes> /// Revision History: /// Name: Date: Description: ///----------------------------------------------------------------- フォーマット2 // =============================== // AUTHOR : // CREATE DATE : // PURPOSE : // SPECIAL NOTES: // =============================== // …

13 c#  documentation  comments 

すでに開発されたプロジェクトを文書化するためにどのオプションが利用できるか知りたいのですが、開発者は1ページも文書を作成しませんでした。 このプロジェクトには、過去2年間にこのプロジェクトに携わった開発者によって作成および変更された機能を備えた多くのスクリプトページ以外の詳細はありません。私が持っているのは、データベーススキーマとプロジェクトファイルだけです。このプロジェクトを組織し、文書化する方法があるかどうかを知りたいので、将来このプロジェクトに取り組む開発者に役立つようにします。 このプロジェクトはPHPとMySQLで開発されました。関数のコメントが不十分であるため、doxygenで実行すると良い結果が得られません。

13 project-management  documentation 

スキーマ設計を適切に文書化したいMongoDBデータベースがあります。MongoDBはNoSQLデータベースであり、本質的にスキーマレスであることを知っていますが、アプリケーションを通じてスキーマを強制し、findOne()結果の印刷よりも優れた方法でスキーマを表現したいと考えています。 私は多くの人がERまたはUMLを使用しているのを見ていますが、私のNoSQLデータベースをリレーショナルDBとして表すのは概念的に正しいとは思えません。少なくとも、奇妙に見えます。 UMLを使用した例：MongoDB：論文でスキーマ図を表す方法は？ 人々は異なるモデルを使用していると思いました。私が検索したところ、スキーマを理解するための素晴らしいTreeビューを提供するMongoVUEがありましたが、プリンターには適していません。 NoSQLの世界で他に見逃しているものはありますか？または、私は休んで伝統的なUMLに固執するべきですか？

13 documentation  uml  nosql  mongodb  diagrams 

閉じた。この質問には、詳細または明確さが必要です。現在、回答を受け付けていません。 この質問を改善したいですか？詳細を追加し、この投稿を編集して問題を明確にします。 4年前に閉鎖されました。 RFC： Request for Comments（RFC）は、インターネットエンジニアリングタスクフォース（IETF）によって発行された、インターネットおよびインターネットに接続されたシステムの動作に適用可能な方法、動作、研究、または革新を説明する覚書です。 この「RESTビデオ入門」の最後に、RFC2616とRFC3986が参考資料として記載されています。ビデオを見た後、私はそれらのドキュメントをグーグルで検索し、タイトルが示すように、それらの使用方法がわからない。それらをすべて読んでメモを取りますか、何かを理解できないか問題が発生した場合の参考としてそれらを使用しますか？

12 learning  documentation 

私は組み込みシステム会社で働くソフトウェア開発者です。プロジェクトマネージャーがいて、プロジェクトの全体的なスケジュール（電気、品質、ソフトウェア、製造など）を担当しているため、ソフトウェアスケジュールは非常に短いです。 私の上司であるソフトウェアマネージャーもいます。彼は、ソフトウェアのスケジュール、設計文書（高レベルおよび低レベルの設計）、SRS、変更管理、検証計画とレポート、リリース管理、レビュー、そしてもちろんソフトウェアの作成と保守をさせてくれます。 ソフトウェアチーム全体（10人のメンバー）に対応するテストエンジニアは1人だけであり、常にいくつかのプロジェクトが進行中です。 私はこれらのドキュメントを作成するのに80％の時間を費やしています。私の上司はプロセスのバックグラウンドから来ており、必要なのはソフトウェアを改善するためのより良いドキュメントであると考えています。 彼はデザインが最重要であると考え、コーディングは「デザインを書き留める」だけで、それほど長くはかからず、「ハードウェアの準備ができる前にすべてのコードを書く」必要があります。 分散モデルとのコラボレーションが簡単だと彼に言った後でも、中央バージョンと分散バージョンコントロールの違いを理解していません。 コードを理解していないため、すべてのバグとその提案された解決策を理解したいと考えています。 検証は開発者が行い、検証はテスターが行うべきだと考えています。ただし、検証では実装が正しいかどうかのみをチェックし（単体テストは作成せず、スケジュールでは考慮されません）、検証はブラックボックステストであるため、単体テストはありません。 私は本当に混乱しています。 これらすべての文書を管理する責任はありますか？本質的に、ソフトウェアプロジェクト管理を行っているような気分になります。技術文書は問題ありませんが、開発者がスケジューリング/計画を立てるべきではないと考えています。 私はドキュメントの作成が本当に好きではありません。問題を解決してコードを書きたいです。私の経験では、設計ドキュメントの作成はある程度までしか役に立ちませんが、コードの改善や高速化の解決策になることはありません。 上司はより良い製品を作ることを本当に気にせず、経営者の目には良いマネージャーになることだけに関心があると思います。 私に何ができる？今年は3か月間実際のコーディングを行い、残りはドキュメントの作成とクライアントからのバグレポートの待機に費やしました。

12 design  project-management  development-process  documentation 

メソッドまたはAPIがコードベースにあるが、実装が完全ではないか、変更される可能性が高いため、使用すべきではないという意味で、「非推奨」と似ているが異なる用語はありますか？（ええ、私は知っています、これらの方法は公開すべきではありません、やだやだやだ。自分の状況を作り出したのではなく、それを最大限に活用しようとしています。） 人々は何を提案しますか？実験的、不完全、他の何か？ まだ流動的なこのAPIのjavadocドキュメントを構築している場合、@ deprecatedタグを使用する必要がありますか、それともより良い規則がありますか？私にとって@deprecatedは、このAPIが古く、新しい優先メカニズムが利用可能であることを意味します。私の状況では、代替手段はありませんが、APIの一部のメソッドは終了していないため、使用しないでください。この時点では、それらを非公開にすることはできませんが、ドキュメントに明確な警告を記載したいと思います。

12 documentation  terminology  api  documentation-generation  javadocs 

重要：ソースコードのドキュメントに問題はありません。これは通常のコード監査に属し、最新の状態に保たれます。私たちの問題は、開発者のドキュメント（または、必要に応じて「外部」）、プログラマーからプログラマーへのブログのような小さなヒントです。 ウィキのようなシステムを使用して、プログラマーのドキュメントを作成します。プログラマーのためにプログラマーが書いた記事は、特定のコードがどのように機能するかをもう少し詳しく説明しています。これらのWikiページには通常、次のものが含まれます。 APIの各部分の設計決定の背後にある動機（たとえば、この特定のサードパーティライブラリがこの方法で何かを行うことを望んでいるため、このotherいことをしました。 特定の一般的なタスクを処理する方法の説明（たとえば、適切なアプリケーションスタイルを参照し、レジストリコンポーネントに自分自身を登録し、他のコンポーネントによって自動的に「スキャン」されるために何らかのインターフェースを実装する必要がある些細なポップアップを表示する） 良い習慣（主観的なもの、実際にこのようなものを書き留めます） 環境設定、必要なツールとそのセットアップ 一般に、主にサイズとブログ投稿/記事のような性質のために通常のコード文書に適合しないコードの記述に関連するもの。 問題 このシステムを導入することは数か月前には良い考えのように思えましたが、最近では解決するよりも多くの問題を引き起こしているように感じます。例えば： 人々は記事を書きます...しかし、コードが変更されると、Wikiの更新はめったに続きません 急いで誰かが書いたスクラッチ記事の多くは、そのように残しました 記事のリクエストは通常​​プロジェクトリーダーからのものですが、正確性や構成についてはほとんど検証されていません。 通常の劣化。コードは変更されましたが、wikiは変わりません。誰かが次に情報を探すとき、彼が通常見つけるのは、時代遅れの低品質のものの束です-そして、何が起こっているのか、彼が見つけたものが正確であるのか、（さらに悪いことに）その一部であるのか疑問に思っています。そして、助けになるはずだったものが、逆になります。 現時点では、プロジェクトリーダーを含め、人々は問題を認識しているようですが、明らかにそれで何かをすることに煩わされる人はいないようです（または、もっと面白いことがあります）。 私の最初の考えは、それをすべて忘却の中に投げ込むことでした（時代遅れの「ヒント」に何回か噛まれた後）。しかし、それは極端すぎるかもしれません。いくつかの情報は注意する価値があり、時々読むことをお勧めしますが、問題は依然として同じです。「最新」にどのように対処しますか？ソースコードに何らかの形でリンクされていますか（したがって、ファイルの更新バージョンがチェックインされると、記事の作成者はコード/記事を修正する必要があるかもしれないと通知されます）？指定された人は、毎日の基本でそれを「見守っていますか」？定期的なクリーンアップを行いますか？

12 project-management  agile  documentation 

ソフトウェア製品の「ドキュメント」と言うとき、それには何が含まれ、何が含まれてはいけませんか？ たとえば、最近の質問で、コメントをドキュメントと見なすかどうかを尋ねましたか？ しかし、これが同様に有効な質問である他の多くの領域があります、いくつかは他のものより明白です： マニュアル（明らかに） リリースノート？ チュートリアル コメント 他のもの？ 線はどこに描かれますか。たとえば、「チュートリアル」がドキュメントの場合、「ビデオチュートリアル」のドキュメントですか、それとも別のものですか？ 一般に、ソフトウェアの何かは、実装、テスト、および文書化されるまで「完了」しません。したがって、この質問は、「完了」したことを検討するために文書化の一部としてどのようなことを検討する必要があります。 私たちの会議での最近の顧客フィードバックからの質問は、私たちのドキュメントがより多くの「サンプル」を必要としていたことを示唆しています。 対象者：データベース、プログラミング言語、および関連ツール（前述のDBの管理クライアントなど）を使用するソフトウェア開発者

12 documentation  terminology 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 4年前に閉鎖されました。 当社は巨大な製品のソースコードを取得しようとしています。 ハンドオーバーの開始時に考慮すべきことは何ですか？すべてを確保し、将来的にその製品を維持できるようにするためですか？

12 documentation  maintenance  knowledge-transfer 

学校プロジェクトのプログラムを文書化する必要があり、「問題ドメイン」というセクションがありますが、このセクションで何を議論するのかわかりません。 質問は次のとおりです。問題の領域で何を議論すべきか。

12 documentation  definition 

現在、AsciiDocと呼ばれるシステムを使用しており、単純なテキストマークアップでドキュメントを作成できます。それから、複数の出力形式を生成できます。pdf出力とchm出力形式のみを使用します。 chmに代わるものがあるのだろうか？私が探しているのは、ソフトウェアでオフラインで使用できるものです（非常に多くのユーザーが非常に離れた場所にいるため重要です）。インデックス（ハイパーリンクされた用語を含むhtmlページと同じくらい単純にすることができます）があり、検索可能で、コードから特定のエントリを呼び出すことができるメカニズムが必要です（状況依存ヘルプと同様）。 この場合のPDFに対する2つのことは次のとおりです。 状況依存ヘルプはオプションではありません 一般的に、ドキュメントはかなり大きい PDFは、状況依存ヘルプよりも印刷されたドキュメントに適しています 私が望むのは、htmlを使用することです。htmlの唯一の問題は、キーワード検索を自動的に提供する方法がわからないように見えることです（ブラウザのctrl + f機能以外-もっとはっきりしたいのですが）。また、キーワードのハイパーリンクインデックスを自動的に生成する方法が見つからないようです。セクションタグがあるため、状況依存ヘルプは簡単です。デフォルトのブラウザに興味のあるページとセクションのURLを渡すだけで、そのページは正しいセクションまで読み込まれます。 私の要件はchmのようにひどく聞こえます-そうです。要件をchmからモデリングしました。私がchmが好きではない唯一の理由は、コードがmapidなどを使用してそれと対話する方法のためです。私のコードがドキュメントのコンテキスト依存部分にアクセスするために使用できるプレーンテキストリスト（自動的に生成されます）を保存することをお勧めします。 私は、html出力ファイルを調べて、見つかったキーワードのリストを単に含むインデックスページを生成するスクリプトを想定しています。明らかに、the、it、isなどのような単語を無視する単語除外メカニズムが必要です。この部分は比較的簡単に記述できます。2番目の部分には、HTMLテキスト内のキーワードとその場所のデータベースをまとめるための何らかのスクリプトが必要です。これは、ブラウザ内で検索メカニズムを提供するとともに、難しい部分になると思います。 代替案に関するアイデアをいただければ幸いです。私はウィキまたはウェブサーバーでホストされている静的なHTMLページのセットをどこかで使用したいと思っていますが、重要なオフライン使用要件があります。htmlをローカルドライブに配置するだけでは、必要な検索要件が提供されません。 編集： 私は、鉱業で使用されるソフトウェアを設計しています。鉱山の多くは非常に離れており、意味のある方法でインターネットにアクセスできません。pdf、html、chmには何も問題はありません（古くなっていることを除きます）。PDFファイルを正しい場所に表示できる場合（つまり、状況依存ヘルプ）、それを使用します。私はほとんど自分で書きたいと思っています-基本的にはポータブルwikiになります。そういえば、ポータブルwikiを提案する場合は、そのようなツールの使用経験のないエンドユーザーについて考える必要があります。それは非常にシンプルでなければなりません。それはchmの美しさであり、連携するのは苦痛ですが、エンドユーザーはそれを気に入っています。

12 documentation  html  help-documentation 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 6年前に閉鎖されました。 私は成長しているオープンソースプロジェクトの作成者です。現在、ドキュメントを管理する最良の方法を見つけようとしていらいらしています。私が検討したオプションは次のとおりです。 HTMLウェブサイト Github Wiki Githubでホストされるマークダウンファイル Github README.mdにすべてのドキュメントを配置する ドキュメントは既にMarkdownで書かれていますが、どのようにそれを利用可能にしたいのかわかりません。ソースを分岐およびタグ付けできるのと同じように、ドキュメントを分岐およびタグ付けできるので、Gitに本当に惹かれています。 Markdownライブラリを使用して、MarkdownをHTMLに変換し、スタイル付きのWebサイトに表示できます。変更があった場合はいつでもWebサイトに変更をアップロードする必要があり、ドキュメントのさまざまな「タグ」をすべて管理することは困難です。 Github Wiki（私の知る限り）は、あなたがいるブランチによって変わりません。そのため、Github Wikiフォームには常に「マスター」バージョンのドキュメントしかありませんでした。 すべてをGithubのREADMEに入れておくと、とてもきれいになります。分岐とタグ付けはできますが、使用するのは少し面倒で、簡単なナビゲーションには向いていません。 素晴らしいソリューションがありませんか？他にどんなオプションがありますか？

12 open-source  documentation 

この2つの違いを理解していますが、同僚から、要件を機能的または非機能的（または移行的）としてラベル付けすることの利点について疑問に思います。なぜそうするのですか？彼は、あるプロジェクトの要件のリストを2日間調べたが、最終結果は「すべてをやる」という命令で別のビジネスエンティティにドキュメントを提出することだったため、彼が言ったことを費やしました。 私が恐れているのは、要件が1つのドキュメントにまとめられていることです。実用的な用語でメリットを説明しようとしましたが、売れませんでした。機能している要件と機能していない要件を文書化する利点を販売するにはどうすればよいですか。

12 documentation  project  management  requirements 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 4年前に閉鎖されました。 プロジェクトを終了するたびに、私が学んだことは常にあります（そうでないと、やる気を起こさせられません）。しかし、私はすべてを思い出すことができず、ずっと後に以前のプロジェクトで遭遇したのと同じ問題に出くわすかもしれませんが、それをどうやって解決したか（または少なくとも私が試みたもの）はありません。 それで、ある種の日記にこれを書き留めておくのは良い考えでしょうか？物事を書き留めることは、ドキュメントを書くことのように感じること（誰もが楽しんでいるわけではない）を知っており、必要なときに私たちの記憶が私たちに役立つことを願っています。しかし、それを文書化すれば、他のプログラマーと共有し、彼らが学んだ教訓を学ぶことができます。 それで、あなたはどう思いますか？

12 experience  documentation  journal