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

ソフトウェアのドキュメントは、コンピュータソフトウェアに付属するテキストで書かれています。ソフトウェアの動作、インストール方法、使用方法、その他のヘルプリソースについて説明します。

3
文芸的プログラミングとセマンティックWebとの関係は何ですか?
この宝石に偶然出会ったとき、私は(通常)技術文書へのセマンティック/オントロジーベースのアプローチを研究していました。 識字プログラミングとセマンティックWebは異なる時代のアイデアであり、関連性があります。 リンクされた論文、Norman WalshによるLiterate Programming in XMLは、セマンティックWebの中心であるXMLテクノロジーについて説明していますが、文芸的プログラミングとセマンティックWeb またはオントロジーベースのドキュメントとの間の概念的なつながりを見ることはできません。助けて?

3
どうすれば複雑なコード構造を文書化できますか?
数学的にも構造的にも非常に複雑で還元不可能なほどのコードがある場合、このコードをドキュメント化するにはどうすればよいですか?特に、私が行う数学または建築のスキルを持っていない可能性のある人がドキュメントからそれを理解できるようにするにはどうすればよいですか?数学もすべて記録する必要がありますか?チュートリアルにリンクしますか?複雑な構造の場合、いくつかの視覚的補助リンクはありますか?

7
プロのソフトウェア開発チームは、重要なプロジェクトの複雑な設計にどのように対処しますか?
まず、私はこの質問が多少長く漠然としていることを理解しており、お詫び申し上げます。これはおそらく、「理解した」人にとっては短い名前の基本的な問題ですが、私はこの点について欠けていると思うので、問題を説明する際はご容赦ください。 私は11歳の頃から、この方法でプログラミングを行ってきました。これは、私が最初から自分にすべてを教えていたことを意味します。私は技術教育を受けましたが、厳密にはコンピュータサイエンスではありませんでした(私はフォトニックエンジニアリングの学位を取得して卒業しています)。もちろんプログラミングコースもありましたが、これは私にとっては基本的なもので、新しいことはあまり学びませんでした。私はその喜びのために自分自身を教育し続けており、プログラミングのキャリアを追求することを常に知っていましたが、その当時の私のプロジェクトはすべて非常に小規模でした。私はそれらを私の心に留め、維持するのに問題はありませんでした。 現在、私はチームでリードしていますが、企業環境ではありません-私は大学でエンジニアリングアプリケーション用の科学ソフトウェア(C ++)を開発しています。突然、プロジェクトは(比較的)大きくなり、ほとんどの場合、私はそれを心に抱くことができなくなりました。主に次の2つのことに多くの時間と労力を費やしています。 しばらく作業していなかったコードのセクションに戻る必要がある場合、それがどのように機能したかを思い出すことが困難です。私は、関連するクラスのヘッダーファイルを確認し、途中でソースファイルに配置したコメントを読むのに多くの時間を費やしています。私が垣間見ることができ、より簡単に画像を取り戻すことができる何らかの「回路図」があるといいのですが。 変更を導入するとき、私がやろうとしていることが他の場所で何かを壊してしまうことの中間点に気付くことがあります(さらに悪いことに、それは実行時にのみ驚きとして現れます)。私は元に戻して別の方法で始めましたが、他のコンポーネントへの影響を無視したことがわかりました。何かが行われる方法、他のコンポーネントに影響を与える方法、変更を実装する前に詳細に計画する方法を確認できる「アーキテクチャダイアグラム」があったらいいのにと思います。 私が一緒に仕事をする人のほとんどは私と同じようなストーリーを持っています-強力な技術的志向と時には素晴らしいスキルですが、彼らの仕事を整理する方法がありません。しかし、彼らのプロジェクトは通常私のプロジェクトよりもはるかに小さいので、彼らはどういうわけか対処します。とにかく、それが私にとって何を意味するかというと、私は一人でいるので、良い実践を学ぶ人がいないということです。 ITの管理に関する大学院のコースを受講しましたが、ITの管理は非常に満足できるものであると感じましたが、主に非プログラマーを対象としており、プロジェクト管理の方法論、予算/スケジュールの見積もり、エンタープライズアーキテクチャなどについて説明しており、ソフトウェアの設計や計画などは担当していません。それは大丈夫です、私もそのことを学ぼうとしています。もちろん、いくつかのツール(UMLなど)とソフトウェア開発プロセスのタイプ(カスケード、反復、アジャイル...)が導入されましたが、明らかにそれほど詳細ではなく、何を選択して使用するかを決めるのに苦労しました(とどの程度)。 私はSOのソフトウェア設計について多くの質問と回答を読んでいます-これまたはその特定のツールまたは方法論を使用してそれを行うことについては多くあります。UMLのドキュメントが私の問題を解決すると確信している場合-私はそれをピックアップし、それを使い始める。しかし、それを誓う人もいれば、役に立たないと言う人もいます。抽象化のより高いレベルでの答えを探しています-私が抱えている2つの問題を解決する方法はありますか。おそらく1つの特定のツールに縛られることなく、それを実行できるようにするには何を学ばなければなりませんか?これらは時々流行から脱却し、プロジェクトの種類によって適用性が異なると思います。 読んでくれてありがとう、私はもっと簡潔に言うことができませんでした(ソフトウェア設計の経験と語彙が不足しています)。

7
他の誰かの過去の仕事をどのように文書化できますか?[閉まっている]
休業。この質問には、より焦点を当てる必要があります。現在、回答を受け付けていません。 この質問を改善してみませんか?質問を更新して、この投稿を編集するだけで1つの問題に焦点を当てます。 4年前休業。 過去の従業員がビジネスクリティカルなシステムに対して行ったカスタマイズに関するドキュメントがほとんどないという悪い状況にあります。Crystal Reports、データベースエンティティ、およびERPソフトウェアの独自の構成/プログラミングファイルに多くの変更が加えられました。 現在のドキュメントは一般的に次のようなものを読みます: このプログラムは、請求の前に実行されます。既知のバグ:なし。 ソフトウェアXのインストール後にこのプログラムを実行します。 このレポートの次のフィールドを変更しました:(方法や理由の説明なし) 私たちのITショップは小規模であり、ERPソフトウェアの場合、ほとんどの作業は1人の担当者(現在は私)に集中して行われたため、他の誰も私たちが行ったことすべてを知りません。ITと経理部門は細かい部分(たまに非常に役立つもの)を知っていますが、それだけでは十分ではありません。 もう1つの問題は、私たちの経理部門が、十分に文書化されていると考えているように見えることです。何が問題だったかについて多くの記録を残していたのは事実ですが、これらの問題を修正するために何が行われたか(もしあれば)についてはほとんど説明されていません。バグを説明する何百もの論文がありますが、変更を説明する文書(上記のように)はほとんど役に立ちません。 すべての処理がわからない場合、過去の変更を文書化するにはどうすればよいですか?私は文書化して起動することができますどのような我々が変更されました:私たちは仕事にシステムを持っている必要があるファイル、データベーステーブルECTを。私たちが何をするかを文書化することもできます。レポートが実行されるとき、なぜ人々がXレポート/プログラムを使用するように言われたか。しかし、これらのカスタマイズされたものの1つに問題がある場合、私はいつも元の状態に戻ります。 自分や他の人のために、この情報を積極的に文書化するにはどうすればよいですか?


5
開発前に最新のアプリケーションをモデリングするための標準は何ですか?
私は最初のエンタープライズレベルのアプリケーションに取り掛かっています。コードを1行もタップする前に、チームでASP.NET MVC C#アプリケーション全体をモデル化してください。 更新:これは、いつアプリケーションを文書化/モデル化するかについての哲学的議論を意図したものではありませんでした。文書化/モデル化の「方法」についてのみ回答を提供してください。 真実は、私がこの部門で常に失敗したことがあり、アプリケーションをこれまで実際にモデル化したことがないということです。これを行うための標準的な方法は何ですか?どのタイプの図を使用する必要があり、ドキュメントはどのように見えますか?サンプルの図とドキュメントへのリンクは高く評価されています。 検索するとき、私はネット上で多くのことを見つけることができますが、これを行う方法について現在のコンセンサスがあるかどうかを確認したいと思いました。 前もって感謝します! おわりに 私はこれがそんなにねばねばした主題であるとは知りませんでした。明白な論争を取り除き、有用な回答を提供してくれた皆さんに感謝します。控えめに言っても興味深い議論でした:) 私が発見した別の便利なリンクはこれです:https : //stackoverflow.com/questions/61487/do-you-use-uml-in-agile-development-practices/61519#61519

4
影響分析文書に何を入れましたか?
したがって、バグを修正しているときに、ソフトウェア製品の他のモジュールに影響を与える可能性のあるバグに遭遇しました。あなたのデータは、修正の影響についてのあなたの主張をサポートするのに十分ではなく、影響分析文書を作成するように求められました。 これを行う方法について定義されたプロセスはありますか? 必要な重要な情報は何ですか? このドキュメントの既知のフォーマット/テンプレートはありますか?

3
要件にWikiを使用する
要件管理を改善する方法を検討しています。現在、Word文書をWebサイトで公開しています。残念ながら、(私の知る限り)あるリビジョンから次のリビジョンへの変更を確認することはできません。私は、wikiやVCSのように(または両方がbitbucket上のwikiのように!)できるようにしたいのですが。 また、各ドキュメントは、開発者が所定の期限までに満たすことが期待される変更について説明しています。蓄積されたアプリ機能のコレクションはどこにも文書化されていないため、レガシーアプリをすばやく修正しようとすると、バグと(設計が不十分な)機能を区別するのが難しい場合があります。 だから私はフィードバックを得たいと思っていました。何について: 誰がいつ何を変更したかを追跡できるようにwikiを使用します(ほとんどの場合、前回の表示以降に編集が行われたかどうかを確認するためにも)。 たとえば、期限ごとではなく製品ごとに1つのwikiページを用意し、実装すべき変更ではなく製品のすべての機能に対応します。このようにして、ページの特定のリビジョンを確認して、特定の時点でアプリが何をすべきかを確認できます。また、次の期限までに要件を実装するための最後のリリース以降のページの変更を確認できます 。 ワダヤシンク?

7
コメント/コード内ドキュメントスタイル
これはばかげた質問かもしれませんが、しばらく頭の後ろにいて、他のどこにもまともな答えを見つけることができません。 私には、説明が1つしかない場合でも、各パラメーターと説明を明示的にリストする必要があると言う先生がいます。これは多くの繰り返しにつながります: double MyFunction(const int MyParam); // Function: MyFunction // Summary: Does stuff with MyParam. // Input: int MyParam - The number to do stuff with. // Output: MyParam with stuff done to it. コード内のドキュメントを書くとき、あなたはどのくらい詳細ですか?

3
フローチャートを使用したRESTインターフェースの文書化
RESTスタイルのWebインターフェースのフローチャート表現の作成に関する提案はありますか?共同開発者に完全なドキュメントを提供するために、製品リソースを変更および生成するためのインターフェースをモデリングするために、いじくり回してきました。 この特定のシステムは、ユーザー認証/リソース数によって異なる動作を開始するため、変更を加える前に、いくつかの明確化を探しています。 複雑さ:全体の構造を単純化してこれを読みやすくするにはどうすればよいですか? 表示記号:これはページを表すのに適していますか? 手動操作記号:これは、ボタンクリックなどのユーザーアクションを表すのに適していますか? 他の提案は大歓迎です。 再投稿をお詫び申し上げます。メインのstackexchangeサイトは、この質問はプログラマーにより適切に提示されることを示唆しています。

5
私は、既存の完全に文書化されていないソフトウェア製品の文書化作業を主導する任務を負っています。どのようなリソースが役立つのですか?
私はテクノロジー企業のソフトウェア開発者です。私が取り組んでいる製品の文書化作業を主導する任務を負っています。目標は開発者の内部でドキュメントを作成することであり、プロジェクトはビジネス側に波及し、そこで要件のドキュメントがカバーされます。 このプロジェクトは挑戦的です。具体的には、次のような製品を扱っています。-少なくとも6年間、長い間使用されています。-あちこちにある古くて小さな断片を除いて、ドキュメントの形式はありません。-コード内にコメントがありますが、それらは技術的であり、包括的な技術的な動作を伝えません(技術的な側面でも)。-ドキュメントがほとんどないか、まったくないため、多くの場合、不必要に複雑になっています。 また、このプロジェクトに取り組む時間はあまりありません。 私は正式な文書やライティングの背景、トレーニング、または経験がありません。私は執筆やオフィス内でのコミュニケーション能力を発揮したため、このプロジェクトに割り当てられたのかもしれません。 このプロジェクトの準備と対処に役立つリソースに関するアドバイスや推奨事項を教えてください。マイルストーンを含む計画の設計を思い付き、ベストプラクティス、タスクの委任、テンプレート、バイインなどについて学ぶために、本/ウェブサイト/フォーラム/その他への参照を探しています。 私は特に、既存の、文書化されていないプロジェクトに優れた文書を導入することをターゲットにしたり、特別な言及をしたりするリソースに期待しています。

2
マイクロサービスアーキテクチャにおける多くのアプリケーションのAPIエンドポイントの維持と文書化
マイクロサービスを使用する上での最大の問題点の1つは、APIが十分に文書化され、APIがダウンストリームアプリケーションに影響を与えずに動作を変更しないことを確認することです。この問題は、相互に依存し合うサービスが多数ある場合に増幅されます。多分その時点であなたは間違ったマイクロサービスをやっていますが、私は余談です。 異なるチームが所有する20のマイクロサービスを継承していて、どのアプリケーションが他のどのアプリケーションのAPIエンドポイントを使用するかについての明確なドキュメントがないとします。これを文書化する規定された方法はありますか?最初に、各アプリケーションのエンドポイントを分析してデータベーステーブルに追加し、多対多テーブル(ほとんどすべてがRailsアプリケーションです)で各アプリケーションとアプリケーションのルート間にFK関係を作成することを考えました。しかし、これがこれを処理するための良い方法であるかどうか、または私はここで車輪を再発明しているかどうかわかりません。 振り返ってみると、マイクロサービスをゼロから始めている場合、これはアプリケーションの相互作用を文書化するのにそれほど悪くない方法かもしれません。これにより、データベースを使用して単一の信頼できる情報源が維持され、エンドポイントへの変更は、データベースの変更と連動してアプリケーションで実行されます。考え?

5
内部APIへの変更が他のプロジェクトを壊すのを防ぐ方法は?
20〜30の独立したモジュール/ソリューションがあります。これらのそれぞれには、クラス、コンポーネントなどが異なる7〜10のプロジェクトがあります。これらはすべて社内で使用されます。 私たちの問題は、1つのモジュールに変更を加える場合、このコードにアクセスしている他のすべてのモジュールを確実に更新する必要があることです。コードベースが異なるため、これを知るのは困難です。 APIのすべての外部使用がどこにあるかをどのように文書化できますか?あるいは、小さな変更が他のモジュールを壊すのを防ぎますか?

3
大規模なソフトウェア会社がコードを文書化またはリファクタリングしないのは一般的ですか?[閉まっている]
休業。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善してみませんか?この投稿を編集して、事実と引用で回答できるように質問を更新してください。 6年前休業。 私は大規模なソフトウェア会社で働き始め、100万行を超えるコードのプロジェクトに割り当てられました。これはクライアント(社内プロジェクトではなく)に販売されるプログラムスイートの一部であり、必要に応じてソースコードを購入できます(ただし、それに関連する追加料金が発生することはまれです)。彼らは何年にもわたってソフトウェア設計を行っており、現在の製品は近い将来に継続することを目的としています。 驚いたことに、何百万行ものコードがドキュメントにほぼ完全に欠けています。さらに、コードの一部の領域は非常に厄介であり、理解しやすくなるようにリファクタリングを使用できる場合があります(たとえば、プログラミング言語の改善が10年ほど前に行われ、コードの大部分が大幅に増加します)バグが発生しにくいことは言うまでもありません)。これを修正するための努力はなさそうで、私が取り組んでいる部分が抵抗に遭遇したためにそうするようにとの私の申し出は、明確な答えを得ることはできませんでした。 これらのプラクティスは、ソフトウェア業界の大企業で一般的ですか?それとも、リファクタリングやドキュメントが不足しているという点で私の会社はユニークですか? 補遺:いくつかのコメントに基づいて、私が探しているものを明確にしたいと思います。私の会社には技術的な負債があることを理解していますが、これは悪いことです。これが原因で私の会社が悪化しているかどうかを判断するのではなく、このドキュメントの欠如とリファクタリングへの抵抗が、私が持つプログラミングの世界での現実であるかどうかを知りたいだけです。私がそれで働き続けるならば対処するために。

1
効果的なC ++ライブラリのWebサイトとドキュメントの作成
C ++ライブラリを作成することは、他のユーザーが使用できるようにドキュメント化することも意味します。また、ドキュメントの品質は劇的に異なる可能性があります。 C ++ライブラリのWebサイトは、最も効果的になるようにどのように構成すべきですか? 私は、「最も効果的な」ことを、図書館の利害関係者の3つの特定のグループに分割することで構成します。 新規ユーザーは、1つのステップから次のステップに明確に流れる、優れた簡単な導入、ダウンロード、セットアップ、およびドキュメントが必要です。 経験豊富なユーザーは、必要な詳細にすばやくアクセスできる確かなリファレンスと、新しい更新に関する明確な情報が必要です。 新しい寄稿者は、寄稿をライブラリーに取り込むために実行する必要があるステップをカバーする方法をガイドする必要があります。 私は彼らが見たり使用したりするものにとても満足する方法を見つけたいと思います。この質問は、プロのプログラミングとユーザーエクスペリエンスとの間のちょっとしたクロスです。 特定の例では、Boostはライブラリの最高のコレクションの1つですが、初期インストール、リファレンスドキュメント、および貢献方法の把握はやや混乱を招く可能性があります。 一方、cppreference.comとSGI STLのドキュメントは、説明、リンク、および例があり、非常に明確で有用であることがわかりました。 例は単なる意見であり、他の例は異なる場合がありますが、それは私が質問している質問にコンテキストを与えるのに役立ちます。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.