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

W3Schoolsは、不完全で、時には不正確であり、広告に乗っているという評判があります。それでも、SOの質問に答えるときにいくつかのことを調べたり、ドキュメントへのリンクを探したりするとき、それはまだ唯一の便利なクロスブラウザリソースです。 以下のような他のリソースがありますMozillaの開発者向けネットワーク JavaScriptを文書化し、ますます素晴らしい仕事をしている、そして伝説的と偉大Quirksmodeが。しかし、彼らは素晴らしいのですが、私が話しているエリアの一部のみをカバーしており、コミュニティ編集や品質管理オプションは提供していません。 共同編集されたクロスブラウザHTML / CSS / JavaScript / DOMエンサイクロペディアを作成する努力を知っている人はいますか？あなたがそうするなら、私はSOがExperts ExchangeにいたようなW3Schoolsへの挑戦者のことを考えています。

12 web-development  documentation  html  css 

休業。この質問には、より焦点を当てる必要があります。現在、回答を受け付けていません。 この質問を改善してみませんか？質問を更新して、この投稿を編集するだけで1つの問題に焦点を当てます。 6年前休業。 プロジェクトでは、いくつかの古いゲームや関連ソフトウェアのさまざまな種類のファイル（構成ファイル、保存、リソースアーカイブなど）を扱う必要があります。これらの大部分はまだ文書化されておらず、それらを操作するためのツールも存在しないため、フォーマットをリバースエンジニアリングして、それらを処理するための独自のライブラリを構築する必要があります。 たいへん需要が多いとは思いませんが、成果を公表したいと思います。ファイル形式を文書化するための承認された標準はありますか？見回すと、いくつかのスタイルが使用されています。.ZIPファイル形式の仕様など、非常に冗長なスタイルがあります。XentaxWikiにあるような他のものはもっと簡潔です-それらのいくつかは読みにくいと思います。私が個人的に最も気に入っているのは、PlayStation 2メモリカードファイルシステムの説明です。これには、詳細な説明テキストとオフセットなどのいくつかの「メモリマップ」の両方が含まれます。これは、私のユースケースに最もよく一致します。フォーマットによって多少異なりますが、私が従おうとするいくつかの一般原則があるはずです。 編集：私が何をしたいのかよく説明していなかったようです。例を作ってみましょう。 構成を「バイナリ」ファイルに保存するいくつかの古いソフトウェアがあるかもしれません-一連のビットフィールド、整数、文字列、そしてすべてが結合されてプログラムによって理解されるわけではありませんが、人間が読めるものではありません。私はこれを解読します。このファイルを解析および変更するためのライブラリーを実装するための仕様として、このファイルの形式を人間が読める形式で正確に文書化したいと思います。また、他の人にもわかりやすいといいですね。 そのような文書が書かれるかもしれないいくつかの方法があります。上記のPKZIPの例は非常に冗長で、主にファイル形式をフリーテキストで記述しています。PS2の例では、値のタイプ、オフセット、およびサイズの表と、それらの意味を詳しく説明しています。XentaxWikiにあるような多くの他のものは、変数のタイプとサイズのみをリストし、ほとんどまたはまったくコメントしていません。 この種のドキュメントの書き方に関するガイダンスを提供するコーディングスタイルガイドに似た標準があるかどうかを尋ねます。そうでない場合、私がエミュレートする必要がある有名な優れた例はありますか？そうでない場合、誰かが少なくともいくつかの有用なアドバイスを要約できますか？

12 documentation  reverse-engineering 

ビジネスルールを文書化する正式で最も一般的に行われている方法は何でしょうか。また、開発成果物のUI仕様をどのように文書化しますか（例：フォームフィールドの文書化、ボタンがフォーム上でどのように動作するか、情報テキストなど）。

12 documentation  business-rules 

現在、「ソフトウェア開発」の研究のために卒業に取り組んでおり、外部企業で複雑なソフトウェアを個別に開発する必要があります。これはすべて、構造化された方法で行われ、対応するすべてのドキュメントを作成する必要があります。 このプロジェクトでは、IEEE要件文書（ソフトウェア要件文書（SRS）、ソフトウェアアーキテクチャ文書（SAD）、ソフトウェア設計文書（SDD））を使用することにしました。別の方法で学校で教えられましたが、このプロジェクトでは、開発前に（代わりに）開発後にSDDを作成することにしました。私の推論は： 私がインターンシップを行っている会社は、実験的な方法で、特定の要件を満たす複雑なソフトウェアを作成するよう指示をくれました。プロジェクトの定義で彼らが私に与えた自由の量のために、事前にほとんど何も確実ではなく、開発プロセスの実験中に最もよく遭遇することができます。さらに、私はソフトウェアを個別に作成していますが、このソフトウェア設計を事前に行うことは、社内の他の誰にとってもメリットがありません。プロジェクトの不確実性により、事前に作成したデザインを大幅に変更する必要があることを確信できるため、事前にそれを行うと、後で変更するのにかなりの時間がかかります。これは逆効果だと感じています。 これは、開発後にSDDを作成する正当な理由ですか？そうでない場合、そのための正当な理由はありますか？ 編集：SDDを後で作成する理由は、将来の開発者がプロ​​ジェクトを継続するためです。私は卒業期間中にプロジェクト全体を終了することはできませんので、他の開発者は現在のコードベースを継続する必要があります。

11 design  documentation  software  iso 

閉まっている。この質問はトピック外です。現在、回答を受け付けていません。 この質問を改善したいですか？ 質問を更新して、 Software Engineering Stack Exchangeのトピックになるようにします。 6年前に閉鎖されました。 私はソースコードにコメントし、ソフトウェア製品を文書化することを提唱しています。私の個人的な経験と観察から、厳密にコメントされているソースコードに取り組んでいると、ソフトウェアの成長や保守が必要になったときにさまざまな方法で役立ったことがわかります。 しかし、コメントすることは最終的に価値がない、またはその価値には疑問があると言う別のキャンプがあります。コメントなしのコーディングの支持者は次のように主張しています。 コードの一部が適切に記述されている場合、それは自明であり、したがってコメントする必要はありません コードが自明でない場合は、コメントを必要としないように、リファクタリングして自明にする テストスイートはライブドキュメントです 時間が経つにつれて、コードとコメントが同期しなくなり、別の頭痛の種になります アジャイルは、ドキュメントの山よりも作業コードの方が重要だと言っているので、コメントを書くことは安全に無視できます。 私にとってこれは単なる教義です。繰り返しになりますが、私の個人的な観察では、賢明で経験豊富な開発者のチームによって作成されたソフトウェアは、最終的に自明ではないかなりの量のコードになります。 繰り返しますが、Java API、Cocoa API、Android APIなどは、高品質のドキュメントを作成して維持したい場合にそれが可能であることを示しています。 これらすべてを言ったが、個人的な信念に基づいたドキュメントの長所と短所およびソースコードへのコメントについての会話は、通常うまく終了せず、満足のいく結論につながらない。 そのため、ソフトウェアドキュメントの影響、特にソースコードのコメント、品質と保守性、およびチームの生産性への影響に関する学術論文と実証研究を探しています。 そのような記事につまずいたことがありますか、もしあればその結果はどうでしたか？

11 productivity  documentation  code-quality  maintainability  engineering 

正規表現にコメントするための一般的な慣行はありますか：正規表現の別の部分を参照するインラインコメントまたはすべての表現に対する一般的なコメントですか？

11 documentation  coding-style  comments 

私たちは、製品ライン全体でドキュメントの改訂を検討しています。その一部は、リファレンスマニュアルのためのプログラミング言語システムの一部として使用します。 プログラミング言語のリファレンスマニュアルを作成する場合、その言語を初めて使用する人に最大限の使いやすさを提供するための最良の方法は何ですか？ 文書化された各キーワードの重要な側面は何ですか？ 構文 説明 引数-該当する場合 戻り値-該当する場合 使用例？ 私が行方不明になっている他の人はいますか？ コンセプト（ロック戦略、パフォーマンス関連の詳細など）もこのリファレンスマニュアルに記載する必要がありますか、それとも別のドキュメントですか？ これは外部消費用です。すでに完全なドキュメントセットがあります（http://www.rocketsoftware.com/u2/resources/technical-resourcesを参照）。私たちが何をすべきかを解決する-私はすでに私のアイデアを持っていますが、いつものように、私は自分の意見だけに頼らないようにします。 対象者：多くの業界でソフトウェアを生産するためにデータベースとツールを使用する技術開発者。

11 programming-languages  documentation 

大学向けのプロジェクトがあり、すぐには始めませんが、かなり長い間考えていました。大学のプロジェクト開発は産業のようなものではないことを理解しています（私は現在インターンです）。そのため、現時点で指摘する状況は、実際のソフトウェア開発者にとってはおそらくばかげているように思われます。^^ ' プロジェクト自体では、多くの作業を文書化する必要があります。したがって、いくつかのマークにカウントされるコードを配信することに加えて、次のようなドキュメントを配信する必要があります。 要件分析ドキュメント プロジェクト計画 ユースケース、オブジェクトモデル、動的モデル、および受け入れテストの計画リスト テストプロセスのドキュメントとテストの成功度 時間の使用などに関する他の議論と分析 これらの成果物は、次の方法で配信されます。 RADファースト プロジェクト計画、ユースケース、モデル、およびテストが続きます（約3週間後） 最後に、実際のプログラムのドキュメント、テストプロセスなど+実際のプログラミング自体（約5週間後） だから、私が理解していることから、これはプロジェクトへのウォーターフォールスタイルのアプローチに向けられています。（私の意見では）唯一の問題は、これが大学のプロジェクトであり、学生がプロジェクト週の学期の終わりにプロジェクトを開発しようとするのと同様に、すでに十分なプレッシャーを持っていることです。学期の終わりにすべてをコーディング/開発/テストしたくはありません。私が対処しなければならない他の多くの評価でパニックに陥ります。 少なくとも、ある種の反復的な開発サイクルを試してみてください。つまり、コーディング/プロトタイピングを早期に開始でき、最後の瞬間にすべてを行うことに集中せず、このプロジェクトを終了する学期の終わり。そして今、私の実際の質問が来ます： すべてのドキュメントを高速の反復/プロトタイピング開発サイクルで提供する必要性を何らかの形で調整できますか？ ドキュメントを反復的に生成するための戦略はありますか？ 私はこれを尋ねて、それが大学で実行可能になると期待しているのはまったく不合理ですか？ また、私はこの質問が非常にローカライズされていることを理解しているので、業界の観点から上記で質問したのと同じ質問をしたいと思います。または会社。 とにかく、これがどれくらい長いのかごめんなさい。最後まで読み終えたら、ありがとう！あなたが答えるために時間をかけることができれば、私は非常に感謝します！ありがとうございました！

11 documentation  iterative-development 

時折、最も重い種類の低レベルの最適化を必要とする十分に計算集約的なコードの1％があります。一般的な例としては、ビデオ処理、画像処理、およびあらゆる種類の信号処理があります。 目標は、コードが保守不能になったり、新しい開発者によって削除されたりしないように、最適化手法を文書化し、教えることです。（*） （*）予測できない将来のCPUで特定の最適化が完全に役に立たない可能性があるにもかかわらず、コードは削除されます。 ソフトウェア製品（商用またはオープンソース）が最速のコードを持ち、最新のCPUアーキテクチャを使用することで競争上の優位性を保持していることを考えると、ソフトウェア作成者は特定の同じ出力を取得しながらコードを微調整する必要があることがよくあります少量の丸め誤差を許容するwhlist。 通常、ソフトウェアライターは、実行される各最適化/アルゴリズムの書き換えのドキュメントとして、関数の多くのバージョンを保持できます。これらのバージョンを他の人がどのようにして最適化手法を研究できるようにするのですか？ 関連： 読みやすいコードと読みにくいコード。いつ線を越えるか？

11 documentation  code-reviews  optimization 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 4年前に閉鎖されました。 基本的にPHPで開発されたWebアプリケーションを完成させましたが、これはもう1つの通常のWebアプリケーションです。通常、最終製品リリースを配信するときは、コードド​​キュメントとアーキテクチャ情報をクライアントに引き渡すだけです。ただし、この特定のプロジェクトでは、クライアントはプロジェクトに関する完全な入出力データを保持することを強く求めています。 だから私はただ疑問に思っています...コードとアーキテクチャのドキュメントとは別にクライアントに提供できる必須の技術的および非技術的ドキュメントは何ですか？ （また、プロジェクトに関するさまざまな統計情報やデータについてクライアントにヒットして、関連する作業量と製品が実際にどれだけクールであるかを実際に知ることもできます。）

11 project-management  documentation  documentation-generation  projects-and-solutions 

有名なオープンソースプロジェクトを勉強してプログラミングスキルを向上させたいのですが、ソースコードに飛び込むだけで簡単に迷子になります。 そこで、最初にコードの構成に関する一般的なアイデアを得るために、設計またはアーキテクチャ（UMLダイアグラムなど）に関するドキュメントを読むことにしました。しかし、驚いたことに、Hibernate、Spring、ASP.NET MVC、Railsなどの大規模なオープンソースプロジェクトのアーキテクチャドキュメントは見つかりませんでした。 だから私は疑問に思い始めました：新しい開発者が読むべきアーキテクチャ/設計ドキュメントがない場合、またはプロジェクトマネージャーがソースコードを開いただけでドキュメントを閉じた場合、オープンソースプロジェクトはどのように成功するのでしょうか？

11 open-source  documentation  asp.net-mvc 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 5年前に閉鎖されました。 最近、ソフトウェアプロジェクトのいくつかの提案を読んでいますが、今まで見てきたことに少し心配です。多くの場合、提案が急ぎすぎたり、考えが不十分だったりしていると感じます。 提案が果物のバスケットのように見える必要はほとんどありませんが、仕事に投球したり、資金調達の承認を求めている場合、「まともな」提案を構成するために利用可能なガイドラインが必要です。 誰かがソフトウェアの提案を書くための良いガイドラインを知っているのか、それとも本/ウェブサイトなどを指し示すことができるのか疑問に思っていましたか？

11 documentation 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 2年前に閉店。 実際にコードを記述する前に、完全なコードドキュメントを最初に作成しようとしたことがありますか？これについては、具体的なインターフェイスを記述し、クラスがどのように相互作用するかを考えさせることで、初期設計がフロア化されないようにするのに役立つと考えたため、以前考えていました。これはいいアイデアですか？誰もが試しましたか？エル

11 documentation 

多くの検索を行った後、ソフトウェア開発の世界で知られていると思われるものに関する基本的な質問に答えることができませんでした。 知られていること： 適切なコードドキュメント（Doxygenタグ、Javadoc、または単なるコメントの豊富さ）に厳格なポリシーを適用すると、コードの開発に必要な時間がオーバーヘッドになります。 だが： 徹底的なドキュメント（またはAPI）を持っていると、新しい開発者やベテランの開発者が機能を追加したり、バグを修正したりするときに生産性が向上（想定）します。 質問： そのようなドキュメントを保証するために必要な追加の開発時間は、将来の生産性の向上によって相殺されますか（厳密に経済的な意味で）？ ケーススタディ、または導き出される結論を裏付ける客観的な証拠をもたらすことができる答えを探しています。 前もって感謝します！

11 java  c#  c++  documentation  coding-standards 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 4年前に閉鎖されました。 文書化されていない/プライベート APIを どのように見つけるのでしょうか？ 例Appleが文書化されていない/プライベートAPIを、駅再生、Windowsの電話7、Win32のカーネル、WindowsのAPI、隠されたコールバックなど、... ハッカーは、プライベートおよびドキュメント化されていない機能について調べるためにどのツールを使用しますか？ APIドキュメントで通常説明されている秘密を明らかにするプライベートAPIとリバースエンジニアリング技術を掘り下げた人々の経験についてどこで読むことができますか？ ありがとう、 A

11 programming-languages  learning  documentation  api