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

ソフトウェア開発会社の主な目標の1つは、バスファクターを増やすことです。これは、Googleが主催した講演でも支持されています。 つまり、明日バスで走り去ってもプロジェクトが継続できるように、すべてをコーディングして文書化する必要があります。言い換えれば、あなたはあなたと同じようなスキルセットを持つ他のプログラマーに簡単に交換できるようにするべきです。 交換可能であることは、開発者の利益に反するものではありませんか？この本では、48の権力法則11 で、権力を得るために人々をあなたに依存させ続け、それが金銭的な報酬に変換されるようにすべきであると述べています。 6か月の一時停止後もプロジェクトを続行するために自分用のドキュメントが必要なシナリオとは別に、開発者とソフトウェア会社の間には明確な利害の対立があるようです。 プログラマーとして、本当に素晴らしいドキュメントと誰でも簡単に読めるコードを書くべきでしょうか。または、それが仕事をし、あなた自身がそれを理解できる方法でコードとドキュメントを書くべきですが、他の人はそれを理解するのに苦労するかもしれませんか？

48 documentation  clean-code 

最も基本的なドキュメントでさえも書くことに嫌悪感があるようです。プロジェクトのREADMEは比較的むき出しです。ドキュメントには依存関係の更新されたリストさえありません。 プログラマーがドキュメンテーションを書くことを嫌うような業界で私が知らないことはありますか？必要に応じてドキュメントの段落を入力できますが、なぜ他の人はそれを嫌うのですか？ さらに重要なことは、ドキュメントを書くことで将来の時間とフラストレーションを節約できることを彼らに納得させるにはどうすればよいでしょうか？

47 documentation  teamwork 

コードで作業するとき、チームメートと同じ課題の多くに直面します。また、有用な関数とクラスをいくつか作成しました。良好なコミュニケーションがあれば、誰かがまとめた素晴らしいことを聞くことができます。6か月後に必要になったときにそれを覚えて、その関数を呼び出して時間を節約できます。覚えていない場合、またはまったく知らない場合は、おそらく車輪を再発明します。 これらの種類のものを文書化する特定の慣行はありますか？どのようにしてそれらを見つけやすくしますか？ チームにそのようなドキュメントがない場合、ホイールがすでに存在するかどうかをどのように確認しますか？ 編集： これまでのところ、答えの1つを除くすべてが理想的な状況を扱っているので、これらのソリューションを要約します。ドキュメントとコミュニケーション。wiki、スタンドアップミーティングなどはすべて素晴らしいものですが、ドキュメントを作成し、ミーティングに参加し、メモを取り、すべてを覚える時間（およびスキル）を持つプログラマーに依存しています。 これまでで最も人気のある回答（Calebの回答）は、文書化や会議ができないプログラマーが使用できる唯一の回答であり、プログラミングを1つだけ行います。プログラミングはプログラマーが行うことであり、もちろん、優れたプログラマーはドキュメント、ユニットテストなどを作成できますが、それに直面しましょう-私たちのほとんどはプログラミングよりもドキュメントを好みます。彼の解決策は、プログラマが再利用可能なコードを認識し、それを独自のクラスまたはリポジトリなどに引き出し、それが分離されているという事実によって、それが見つけやすくなり、それを使用するための学習曲線を容易にすることです... 。そして、これはプログラミングによって達成されました。 ある意味では、このように見えます。3つの関数を書いたばかりで、他の誰かがそれらについて知っておく必要があると思います。私はそれらを文書化し、書き、会議で発表することができます-私はできますが、それは私の強さではありません-または....私はそれらをクラスに抽出し、それをうまく命名し、それらをブラックボックス、および他のクラスファイルが行く場所に貼り付けます。その後、それを発表する短いメールは簡単です。他の開発者はコードをスキャンして、完全に理解していないコードで使用されている分離された関数よりもよく理解できます。そのコンテキストは削除されます。 これは、適切な名前のメソッドを備えた適切な名前のクラスファイルのセットを持つことは、優れたプログラミングによって達成される優れたソリューションであることを意味するため、これが気に入っています。会議を必要とせず、詳細な文書の必要性を和らげます。 この流れに他にもアイデアはありますか？

43 documentation  teamwork  team  code-reuse 

このタイプのコード（C ++）ドキュメントに役立つコメントを（できれば）書いていることに気付きました The reason we are doing this is... 「私」の代わりに「私たち」を使用する理由は、「私たち」が好まれることが多い学術論文をたくさん書いているからです。 だからここに質問があります。コードを文書化する際に一方を他方に優先させる正当な理由はありますか？ 「私たち」を使用：これを行う理由は... 「I」を使用：これを行う理由は... 私の名前を使用してください：理由[my name]は... 受動態：これが行われた理由は... どちらでもない：これを行うのは... 私はその方法を書くのに慣れているので＃1を選択しますが、ドキュメントはライター向けではなく、読者向けです。コードを保守するときに変更されます。

41 documentation 

私の学校のCSプログラムでは、オブジェクト指向プログラミングについては一切言及していません。そのため、私はそれを補足するために独力で読んでいます。具体的には、Bertrand MeyerによるObject Oriented Software Constructionです。 Meyerは、クラスが実装に関する可能な限り多くの情報を隠すべきであると繰り返し指摘していますが、これは理にかなっています。特に、彼は、属性（つまり、クラスの静的で計算されていないプロパティ）とルーチン（関数/プロシージャ呼び出しに対応するクラスのプロパティ）を互いに区別できないと繰り返し主張しています。 たとえば、クラスPersonに属性がある場合、定数属性として定義されている場所またはのようなものに内部的に対応するageかどうかを表記法から判断Person.ageすることは不可能であると主張します。これは私にとって理にかなっています。ただし、彼は次のように主張し続けています。return current_year - self.birth_datereturn self.ageself.age クラスの短い形式として知られるクラスの標準クライアントドキュメントは、特定の機能が属性または関数のどちらであるかを明らかにしないように考案されます。 つまり、クラスのドキュメントでさえ、「getter」が計算を実行するかどうかを指定することを避けるべきだと主張しています。 これ、私は従わない。この区別をユーザーに知らせることが重要になるのは、ドキュメントだけではありませんか？Personオブジェクトで満たされたデータベースを設計する場合Person.age、高価な呼び出しかどうかを知ることは重要ではないので、何らかのキャッシュを実装するかどうかを決定できますか？彼が言っていることを誤解していませんか、それとも彼はOOP設計哲学の特に極端な例ですか？

39 design  object-oriented  documentation  performance 

技術仕様とは何ですか？それらは設計文書と同じですか？そうでない場合、違いといくつかの例は何ですか？

38 documentation  specifications 

私たちは、プロジェクトのドキュメント作成プロセスをGoogleドキュメントから自己ホスト型のGitリポジトリのセットに移行しようとしています。 テキストドキュメントはGitに十分対応しています。通常、高度な書式設定は必要ないので、複雑な場合にLaTeXを埋め込むオプションを使用して、すべてをたとえばマルチマークダウンに変換します。 しかし、スプレッドシートはまったく別の話です...バージョン管理システムにやさしい（そして、できれば、Markdownと同じくらい人間が読める）spreadsheed（-like）形式はありますか？ 「フレンドリーなフォーマット」：Gitはフォーマットでうまく機能し（XML では機能しません）、人間が読めるdiffを生成します（外部ツールを含む追加の設定はOKです）。 明らかに、Markdownフレーバーを使用すると静的テーブルを作成できますが、次のようなものを使用できるようにしたいと思いSUM()ます...（CSVにも同じ問題があることに注意してください。）いいね 更新：Linux向けの回答のみ、お願いします。MS Officeのものはありません。

35 version-control  documentation  tools  linux 

私の会社は、市場調査データの管理を改善しようとしています。 現在のデータ管理スタイル： 「ねえ神保、WhatZit 2.0の写真はどこにありますか？ 「ええ、私はその会社からその会社についてのメールを覚えています。数分でOutlookを検索してください」 「重要な競合他社の製品カタログの最新のコピーを持っているのは誰ですか？私のものは2009年からです。」...「コリーンはそうします、そして彼女は産休中です。ワークステーションのパスワードを得るために彼女に電話する必要があります...」 望ましいデータ管理スタイル： トピック（法律、経済、産業、競合他社）ごとに整理されたデータ トピックごとに、複数のメディアタイプ（会社の製品画像、プレスリリース、連絡先情報）が一緒に保存されますが、それでもタイプ別にきちんと並べ替えられます データ編集履歴 共同アクセス（データサイロなし） 私は、すべてのユーザーがアクセスできる部門wikiをセットアップすることを考えていました。上記の4つの基準を満たしているように見えますが、画像ギャラリーや記事の書式設定などのより高度な機能がユーザーフレンドリ（読み方：技術に詳しくない人でも解読可能）であることに少し懸念があります。 ここの誰かが非ITの人々のためにwikiをセットアップし、それが燃えたり、ゴーストタウンになったり、ジオシティのように見えたりしませんでしたか？ おまけの質問：この問題を解決するためにMediaWiki（または他のwiki）を選択した場合、明らかな欠点がありますか？ （私はあなたの何人かが以前にこの問題に遭遇し、いくつかの洞察を提供できることを望んでいます...）

35 documentation  cms  wiki 

私は、インラインドキュメントも技術ドキュメントも持たない既存のアプリケーションのチームの一員として働いています。アプリケーションのさまざまなバグレポートに取り組んでいるので、さまざまな場所にあるバグ番号-バグ番号を書いて、次の開発者がそのバグ番号を参照して何が起こっているのかを確認できるようにしました。 したがって、私の質問は次のとおりです。 このコードを文書化する最も効率的な方法は何ですか？領域に触れたときに文書化する必要がありますか（ウイルスの場合はウイルス手法）、またはアプリケーションの他の領域に分岐するパスをたどらないで、各セクションから単独で文書化する必要がありますか？以前に存在しなかった場所にインラインコメントを挿入する必要があります（コードが何をするかを誤って特定する恐れがあるため）。 既存のインラインドキュメントも、外部ドキュメントへのインライン参照もない、かなり大きなアプリケーションを正確かつ迅速にドキュメント化するには、どの方法を使用しますか？

35 documentation  language-agnostic  methodology 

私は現在、政府の請負業者のインターンであり、Wordはソフトウェア開発プロセスの事実上の標準であるという（当然のこととして避けられない）感じを抱いています。 そのバイナリ形式により、コードベースでの共同作業に慣れている方法でドキュメントを共同作業することは非常に困難です。（ラテックス、Markdownを、再編テキスト、などの言語のプレーンテキストマークアップの使用などは）開発者の通常のワークフローとうまく動作差分フレンドリー文書が可能になります。言語でサポートされていないコメント（Markdownなど）については、マークアップを含む他のプレーンテキストファイルに簡単に適用できるコードベース（GitHub、Bitbucketなど）での共同コメントを可能にする多くの既存のソリューションがあります。 技術的に知識のない管理と協力する必要があることは、あらゆるものに何らかのグラフィカルインターフェイスを必要とすることを理解していますが、これらの形式のほとんどにはそのようなインターフェイスが存在します。たとえば、LaTeXにはLyXと呼ばれる種類の「分岐」があり、グラフィカルなフロントエンドをプレーンテキストのLaTeXのような構文に置きます。このファイルは、主にその編集においてグラフィカルであるにもかかわらず、依然として差分に対応しています。（Wordスタイルのコメントもあります。）これらのソリューションの多くは、Wordの代わりに使用することができ、その大半は無料またはオープンソースです。 ただし、他の誰にも見られない独自の内部ドキュメントにもWordを使用しています。私たちは、キャリアのかなりの部分をテキストで処理します。ドキュメントが特別なのはなぜですか。ささいな「私たちはこれ以上何も知りませんでしたが、今ここで立ち往生しています」とは別に、そのような決定を支持する理由がなければなりません。文書を書く他の、より口語的な（そして議論の余地なく強力な）手段の代わりに平文の文書を使用する際に、ソフトウェア開発プロセスが直面する課題は何ですか？ 理由は異なるため、おそらくこれら2つの密接に関連するシナリオに個別に回答する必要があります。 最初からプレーンテキストのドキュメントを使用する 長期にわたるプレーンテキストドキュメントへの移行

33 development-process  documentation 

人々はいつReadmeファイルを書き始めましたか？ フォーマットに関係なく、ほとんどすべてのプログラムにこのファイルがあるようです。 このドキュメントの最初の使用が文書化されていますか？

32 documentation  terminology  history 

java apiなど、よく文書化されたコードの良い例があります。しかし、gitや企業の内部プロジェクトなどの公開プロジェクトのコードの多くは、文書化が不十分であり、初心者にはあまり適していません。 私のすべてのソフトウェア開発スティントでは、文書化が不十分なコードを処理する必要がありました。次のことに気づきました- コード内のコメントはほとんどまたはまったくありません。 メソッド名と変数名は自己記述的ではありません。 コードがシステムまたはビジネスプロセスにどのように適合するかについてのドキュメントはほとんどまたはまったくありません。 悪い開発者を雇うか、良い開発者を指導しない。シンプルでクリーンなコードを書くことはできません。したがって、開発者を含む誰にとってもコードを文書化することは困難または不可能です。 その結果、多くのコードを調べて、多くの人と話して物事を学ぶ必要がありました。これはみんなの時間を無駄にすると感じています。また、プロジェクトへの新規参入者向けのKT /ナレッジ転送セッションの必要性も生じます。 次の理由により、ドキュメントには値する注意が払われていないことを学びました。 怠惰。 開発者はコード以外は何もしません。 雇用保障。（コードを簡単に理解できる人がいない場合、簡単に交換できない可能性があります。） 期限が厳しいため、文書化する時間がほとんどありません。 ですから、会社やプロジェクトで優れた文書化の実践を奨励し、実施する方法があるのだろうかと思っています。プロジェクトの複雑さに関係なく、システムの適切なドキュメントとプロジェクトのコードを作成するために使用する戦略は何ですか？最小限のドキュメントが必要な場合やドキュメントが不要な場合の良い例はありますか？ 私見、私は私達がプロジェクトが渡された後文書の検討があるべきであると感じます。単純で簡潔、説明的で使いやすいものでない場合、開発者または技術文書エンジニアがその責任を負い、修正する必要があります。私は、人々が最初の本のようにユーザーフレンドリーになることを望んではなく、ドキュメントの連を作ることを期待していませんが、何時間もの分析と無駄なKTセッションの必要性を排除すると期待しています。 この狂気を終わらせる、または軽減する方法はありますか？「ドキュメント駆動型開発」でしょうか？

26 programming-practices  development-process  documentation  source-code  sdlc 

私の職場では、「アジャイル」とは「あいまいな要件、受け入れ条件の悪さ、幸運」を意味することが多いという課題に直面しています。私たちは、一般的な改善努力として、それに対処しようとしています。 そのため、その一環として、ユーザーストーリーレベルを超えて、システム内の特定の機能の影響の予備調査の結果を正確に反映し、私たちが持っている質問への回答を含む設計ドキュメントを生成することを提案していますビジネスに尋ねた。 これに効果的な基準はありますか？ 現在、新しい機能が「泥の大玉」システムの複数の領域に影響を与える可能性がある状況に直面しており、この技術的負債により見積もりが上昇し始めています。うまくいけば、より思慮深い設計プロセスが役立つことがあります。

25 design  agile  documentation 

象徴的な「Given-When-Then」シナリオ構文を使用した動作駆動型開発は、ソフトウェア機能評価の境界オブジェクトとして使用できる可能性があるため、最近非常に誇張されています。 Gherkin、またはどちらの機能定義スクリプトでも、ビジネスで読み取り可能な DSLであり、すでにそのような価値を提供していることは間違いありません。 ただし、プログラマではない人が書き込み可能であることに同意しません（Martin Fowlerも同様です）。 プログラマ以外の人が作成し、開発者がインスツルメントしたシナリオのアカウントを持っている人はいますか？ 書き込み可能性の欠如についてコンセンサスがある場合、シナリオを開始してそれらをインストルメント化する代わりに、実際のテストからビジネスで読み取り可能なシナリオを生成するツールに問題がありますか？ 更新：「シナリオジェネレータ」ツールに関しては、もちろんビジネス言語を魔法のように推測することはありません;）しかし、現在、正規表現マッチャーを使用して（抽象化次元で）トップダウンアプローチでテストを作成するように、ボトムアップアプローチでシナリオを作成する文字列ビルダー。 「アイデアのみを提供する」例： Given I am on page ${test.currentPage.name} And I click on element ${test.currentAction.element} …

24 documentation  bdd  documentation-generation  business-rules 

私は数年前からプロジェクトに取り組んでおり、まともなユーザーベースを集め始めています。いくつかの基本的なドキュメントを含むプロジェクトページを作成しましたが、現時点ではFAQにすぎません。新しいユーザーとパワーユーザーの両方にとってより有益になるように改善する必要があることを知っています。そして、それは次のリリースのToDoリストにあります。 ただし、次のリリースには、ユーザーベースが取得したい機能があります。今すぐリリースする準備ができており、パッケージ化されており、すぐに使用できます。適切な配布サービスに展開するだけです。 ポイントへ。この機能はユーザーにとって重要ですが、ドキュメントは私にとって重要です。ドキュメントを書き直すまでリリースを待つべきですか？私の現在のユーザーベースは、新機能の使用方法を理解するのに十分な知識を持っているので、心配していることではありません。このプロジェクトに取り組む自由な時間は限られているため、ドキュメントを完成させるのに数週間かかる場合がありますが、もう待つようにするとコミュニティは唾を吐きます。 このシナリオで顧客は正しいですか？新規ユーザー向けの堅牢なドキュメントよりも、既存のユーザー向けの素晴らしい単純な機能を優先すべきでしょうか？ 更新：うわー、非常に多くの素晴らしい、高品質の応答！プロジェクトとそのユーザーの両方をどのようにやり取りし、サポートする必要があるかについて、あなたが本当に助けてくれました。感謝万円！

23 documentation