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

私はプログラミング言語の設計を本当に楽しんでいます。私の言語プロジェクトとその潜在的なユーザーは、包括的な標準ドキュメントの恩恵を受けると思うことがあります。私は非常に形式的な（C ++）からやや非公式な（ECMAScript）に至るまで、多くの言語標準を見てきましたが、物事をどのように分類し、そのようなドキュメントを整理するべきかについて、実際には理解できません一般的にテクニカルライティングが得意だと思います。 長いチュートリアルのように書くべきですか、それとも正式な数学論文のように書くべきですか？リファレンス実装と並行して開発している場合、どうすれば最新の状態に保つことができますか？実装とドキュメントを事実上の標準としてあきらめて扱うべきですか？さらに、規格を持つことには本当に大きな利点がありますか？必要な言語は不必要に複雑であることを標準平均を？

16 programming-languages  documentation  standardization 

私は、クライアントにとって有効で目的に合った製品に取り組んでいます。 LAMPスタック（PHP / Cake）上に構築されているため、GPL、MIT、PHP、APACHEライセンスがあります。 「現状有姿」、いかなる種類の保証または条件もなしに、明示、黙示を問わず、タイトル、非侵害、商品性、または特定目的への適合性の保証または条件を含むがこれらに限定されない。お客様は、作品の使用または再配布の適切性を判断する責任を単独で負い、本ライセンスに基づく許可の行使に関連するリスクを負います。 私の製品は有効であり、目的に合っているという理論的根拠： 署名されたUAT文書は、妥当性と目的への適合性を証明します。 スタックは、開発者、業界、およびエンドユーザー（netcraft、gartnerなどの統計情報）で広く使用されているため、目的に合っているというコンセンサスが得られています。（つまり、保証免責事項の目的適合性ステートメントをある程度無視することができます） これは有効なポイントですか？自分のソフトウェアが目的に合っていると主張できますか？

15 licensing  documentation  specifications 

現在、大学で提供されているソフトウェアエンジニアリングおよびキャップストーンデザインコースの新しいカリキュラムを開発するために、大学の教授と協力しています。 最近まで、両方のコースでウォーターフォールモデルを排他的に使用していたため、学生は長い時間をかけてレポートを作成していました。私からの多くのプレッシャーの後、私の教授は、この学期にスクラムをソフトウェアエンジニアリングカリキュラムに含めることにしました。 学期の前半はまだ滝のようで、学生は40ページの設計レポートとソフトウェア仕様書を書きました。学期中期には、すべてのチームがアプリケーションのデモをリリースする必要がありました。その時点で、コースはスクラムに切り替わり、3週間のスプリントが2回行われました。現在、ウォーターフォールを完全に排除し、スクラムベースのカリキュラムのみを作成する方法を考えています。 残念ながら、スクラムと学生の間でいくつかの非互換性が発生しました。 毎日のスクラム会議は、学生にとってほぼ不可能です。授業中であっても、教授が通常講義しているため、学生がスクラム会議を開催するのは不便です。 学生は経験が浅いため、何か時間がかかるのを正確に予測できないため、ポイント/時間の推定は困難です。 スクラムは、常勤の同じ場所にいる開発者に最適ですが、学生もそうではありません。せいぜい、学生はコースに週15〜20時間を捧げ、仕事の会議を開催することは非常に困難です。チームには最大10人の生徒を含めることができます（常に1人または2人の怠け者がいます）。 教授はドキュメントを切望しています！スクラムレポートは聞いていません。バックログとバーンダウンチャートだけです（アカデミックをなだめるのに十分かどうかはわかりません）。 学生はしばしば、アジャイルは「すぐにジャンプして、振り返らずにコーディングを開始する」ことを意味すると思います。これは、想像できる最も恐ろしいコードの一部につながります。したがって、50ページのドキュメントやUMLダイアグラムの山を必要とせずに適切な設計を実施する方法を探しています。 これらの問題を考えると、教授と私はスクラムをアカデミックな環境で機能するようにどのように適応させることができると思いますか（そもそもスクラムを気にする必要がありますか）。また、ウォーターフォールモデルを教えることにはまだ価値がありますか？ フィードバックを事前にありがとう！

15 agile  scrum  documentation 

閉まっている。この質問はトピック外です。現在、回答を受け付けていません。 この質問を改善したいですか？ 質問を更新して、 Software Engineering Stack Exchangeのトピックになるようにします。 6年前に閉鎖されました。 プロジェクトの内部ドキュメント、仕様、要件などを整理および維持するためのソフトウェアを探しています。現在、すべてのドキュメントを多数のMS Word DOCファイルとしてソース管理リポジトリに保存しています。これによりバージョン管理が可能になります。ただし、この情報を検索したり、それらの間にリンクを作成したり、分類したり、共同作業したりすることはできません。 要件、設定： クライアント側でのゼロインストール（WEBベース）。 ドキュメントのバージョン管理。 ドキュメントの注釈。 ドキュメントのリンク。 完全検索（すべてのドキュメント）。 MS Word（* .doc）import \ export。 WYSIWYGテキストエディター。 これまでに発見して試したシステム： MediaWiki XWiki 合流

15 project-management  documentation  knowledge-management  knowledge-base 

JSONがJavaScript Object Notationの略である場合、JSONオブジェクトと言うとき、あなたは本当に「JavaScript Object Notationオブジェクト」と言っているのではないでしょうか？ 「JSON string」と言う方が正しいでしょうか？ それとも、単にJSONと言う方が正しいでしょうか？（「これらの2つのサービスは、それらの間でJSONを渡します」のように。）

15 documentation  grammar  json 

仕様の作成についていくつか質問があります。 ソフトウェア仕様を作成するとき、トピック「ユーザー要件定義」の下で、「機能」と「制約」のみを指定する必要がありますか？ 「ユーザーインターフェイス」は「機能」または「制約」に分類されますか？ ソフトウェアを分割できる主な主要領域（要件）は何ですか（UIなど）。

15 documentation  requirements 

技術的な（将来の開発者向けの）ドキュメントはどれくらいですか？適切なコーディング時間と文書化時間の比率はありますか？ パパディモウリスはあなたがすべきだと主張する 最も理解しやすくするために必要な最小限のドキュメントを作成し、 それは良いガイドラインですか、それとも私が作成すべき具体的なものはありますか？

15 documentation 

当社は、多くの手動のビジネスプロセス（および関連する組織の知識）を新しいエンタープライズソフトウェアに変換するプロセスを進めています。このプロジェクトは順調に進んでいますが、先に進むと、ビジネス側と開発側の両方で用語と定義に関して多くの混乱があることが明らかです。 ユビキタス言語を形成するというEvanの議論をしばらく知っていましたが、正式に文書化する必要があるのはこれが初めてです。ULの用語をどこで/どのように文書化するかを考えてみようとすると、ちょっと迷ってしまいます。 他社はユビキタス言語をどのように文書化していますか？これは単なるWikiスタイルの辞書ですか？この目的のためのツールはありますか？

14 documentation  domain-driven-design 

私は最近、不変オブジェクトの有用性につまずきました。たとえば、要素をコンストラクタに渡し、クラスを不変にする必要がある場合、これらの要素が不変でない場合はこれらの要素をコピーする必要があります。 これには、プロジェクトに関する多くの確認または知識が必要です。 public A(B foo) かつB不変ではない、A私はコピーする必要があるだろうB。今でBは不変のように思えますが、それ自体はコンストラクタなどに可変クラスを持っています。 Javaでクラスが不変である場合、文書化するための標準またはベストプラクティスはありますか？@immutableJavadoc にはキーワードがないようです。 @Immutable注釈は自動クラスの生成ではなく、標準のJavaの一部については全く違うもののようです。

14 java  documentation  immutability 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 4年前に閉鎖されました。 現在、大学のカリキュラムに含まれていないPythonを学んでいます。インタビューの中で、なぜPythonを選んだのかと尋ねられ、簡単に学ぶことができ、ドキュメントが非常によく書かれていると答えました。インタビュアーは、それが十分な理由であるかどうかは答えませんでした。彼は確信しているように見えましたが、私にはわかりません。 よく書かれたドキュメントと習得の容易さは、スクリプト言語を選択する十分な理由ですか？または、Pythonライブラリの利用可能性とPythonのより大きなユーザーベースについて詳しく説明する必要がありますか？ ちょっとだけ。Pythonはこの仕事には必要ありませんでした。同社は、Ruby-on-railsに取り組みました。Pythonは私の履歴書にあり、インタビュアーはプログラミング言語を選択する際に、私がより新鮮なものとして考慮したことを知りたかっただけだと思います。

14 learning  python  interview  documentation 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 4年前に閉鎖されました。 同様に、オープンソースプロジェクトの設計やアーキテクチャに関するドキュメントがなくても成功する方法はありますか？質問、私は好奇心が強いです：なぜこれほど多くのライブラリがエンドユーザーのドキュメントにそれほど欠けているのですか？ 私の見解はこれです： ほとんどの人は、ソースコードを書くよりもソースコードを読むのが難しいことに同意します。 ドキュメントがなければ、ライブラリを使用するにはライブラリのソースコードを読む必要があります。 したがって、文書化されていないライブラリを使用することは、ライブラリをゼロから再作成するだけではありません。 その結果、人々にライブラリを使用してもらいたい場合は、文書化されていることを確認してください。 多くの開発者がドキュメントを書くことを好まないことは知っていますし、退屈な作業になる可能性があることに同意します。しかし、それは不可欠な仕事です。世界で最高のプログラマーインターフェースを持つよりも、ライブラリに優れたドキュメントがあることが重要です。（人々は常にくだらないライブラリを使用します;文書化されていないライブラリを使用する人はほとんどいません） ああ、ドキュメントを言うとき、私は本当のドキュメントを意味することに注意してください。Sandcastle / Javadoc / Doxygenボイラープレートではありません。

14 documentation 

SCRUMプロセスにテストプロセスを統合しています。私の新しい役割は、後で自動化するためにWebアプリケーションの受け入れテストを作成することです。テストケースの作成方法について多くのことを読みましたが、複雑なWebアプリケーション用のテストケースを作成するための実用的なアドバイスを提供してくれる人はいませんでした。 テストケースは短くする必要があります。CMSの例を取り上げます。短いテストケースは、保守が容易で、入力と出力を識別するのが簡単です。しかし、長い一連の操作（たとえば、ドキュメントの追加、他のユーザーへの通知の送信、他のユーザーの返信、ドキュメントの状態の変更、ユーザーへの通知など）をテストする場合はどうでしょうか。むしろ、テストケースは完全なシナリオを表す必要があるように思えます。しかし、これにより、明らかに複雑なテスト文書がどのように生成されるかがわかります。 テストでは、入力と出力を特定する必要があります。：動作が異なる、相互作用するフィールドが多数ある長いフォームがある場合はどうなりますか。すべてに対して1つのテストを作成しますか、それとも1つのテストを作成しますか？ テストケースは独立している必要があります。しかし、アップロード操作のテストに接続操作の成功が必要な場合、どのように適用できますか？そして、それはテストケースの作成にどのように適用されますか？各操作に対してテストを作成する必要がありますが、各テストはその依存関係を宣言しますか、それとも各テストのシナリオ全体を書き換える必要がありますか？ テストケースは、軽く文書化する必要があります。この原則は、アジャイルプロジェクトに固有のものです。それでは、この原則を実装する方法について何かアドバイスはありますか？ 受け入れテストケースの作成は簡単だと思っていましたが、私がしなければならないすべての決定に圧倒されました（参考：私は開発者であり、プロのテスターではありません）。私の主な質問は次のとおりです。複雑なアプリケーションの保守可能な受け入れテストケースを作成するために、どのような手順またはアドバイスがありますか。ありがとうございました。 編集：私の質問を明確にするために：受け入れテストは要件から開始し、アプリケーション全体をブラックボックスと見なす必要があることを認識しています。私の質問は、テストドキュメントを作成し、テストケースを特定し、テスト間の依存関係に対処するための実用的な手順に関するものです...複雑なWebアプリケーションの場合

14 testing  documentation  acceptance-testing 

私は、主な仕事がSCADAとPLCであり、他の制御システムのスタッフと一緒に、制御システムの会社で働いています。 ソフトウェア開発は、社内のプロジェクト管理および評価システムを作成する決定が下されるまで、あちこちで少しだけ離れて、会社が実際に行うものではありません。 このプロジェクトは、もともとソフトウェアの人としてここに来た人々によって引き継がれ、私たちはほとんどジュニアです。 プロジェクトは小さなものから始まったので、デザイン、データベースなどのようなものだけをドキュメント化しましたが、コーディング形式/規約については実際には合意しませんでした。 StyleCopを使用してコードを適切に文書化したことを確認しましたが、適切な標準を継続し、今後大きな開発作業が行われる場合は誰でも作業できるように、コーディング規約/プラクティスの公式文書が必要だと感じています良いベースプレートがあります。 そこに問題があります、コーディング規約と標準のための文書をどのように作成するのか分かりません、私が考えることができるのは良いプラクティスと悪いプラクティスの例です（たとえば、変数に名前を付けるときのキャメルケース、ハンガリー語の表記を避けるなど）有能なプログラマー（明らかに）ですが、この種のチャーターはありません。 それにポイントを置くために、私の質問は次のとおりです。良いコーディング標準文書の重要な側面と内容は何ですか？

14 programming-practices  documentation  coding-standards  standardization 

私は現在、2つのシステムを使用してコードドキュメントを記述しています（C ++を使用しています）。 Doxygen形式を使用して、メソッドとクラスメンバーに関するドキュメントがコードの横に追加されます。サーバーでは、Doxygenがソースで実行されるため、Webブラウザーで出力を確認できます。 概要ページ（クラスのセット、アプリケーションの構造、サンプルコードなど）がWikiに追加されます。 メンバーやクラスに関するドキュメントはコードに非常に近いため、このアプローチは簡単だと個人的に思いますが、概要ページはWikiで編集するのが非常に簡単です（また、画像、表などを追加するのも簡単です）。Webブラウザを使用すると、両方のドキュメントを表示できます。 私の同僚は、すべてをDoxygenに入れることを提案しています。これは、MicrosoftのHTML WorkShopまたはQt Assistantを使用して、すべてを含む1つの大きなヘルプファイルを作成できるためです。私の懸念は、特に表、画像などを追加する場合、Doxygenスタイルのドキュメントの編集がはるかに難しいことです（Wikiと比較して）（または、生成する必要のないDoxygenの「プレビュー」ツールがありますか？結果を見る前のコード？） 大きなオープンソース（またはクローズドソース）プロジェクトは、コードド​​キュメントを書くために何を使用しますか？彼らはこれをDoxygenスタイルとWikiに分けていますか？または、別のシステムを使用していますか？ ドキュメントを公開する最も適切な方法は何ですか？Webサーバー/ブラウザ経由、または大きな（数MBの）ヘルプファイル経由？ コードドキュメントを作成するとき、どのアプローチを取りますか？

13 documentation  documentation-generation  wiki 

詳しく説明すると、1人のプロジェクト（チームのソース管理、ドキュメント、ビルドなど）を実行している間に配置する必要があると考える人々と、2人目が来るまで何をする必要がないかを知ることに興味があります。プロジェクトに。 このシナリオを経験したことがある人なら誰でも、彼らの洞察に感謝します。

13 project-management  version-control  development-process  documentation  builds