Movatterモバイル変換


[0]ホーム

URL:


はてなブックマークアプリ

サクサク読めて、
アプリ限定の機能も多数!

アプリで開く

はてなブックマーク

  • Twitterでシェア
  • Facebookでシェア

気に入った記事をブックマーク

  • 気に入った記事を保存できます
    保存した記事の一覧は、はてなブックマークで確認・編集ができます
  • 記事を読んだ感想やメモを書き残せます
  • 非公開でブックマークすることもできます

新型コロナウイルスに関する情報は、厚生労働省の情報発信サイトを参考にしてください。情報を見る

適切な情報に変更

エントリーの編集

loading...

エントリーの編集は全ユーザーに共通の機能です。
必ずガイドラインを一読の上ご利用ください。

タイトルガイドライン

このページのオーナーなので以下のアクションを実行できます

タイトル、本文などの情報を
再取得することができます
コメントを非表示にできますコメント表示の設定

ブックマークしました

ここにツイート内容が記載されますhttps://b.hatena.ne.jp/URLはspanで囲んでください

Twitterで共有

ONにすると、次回以降このダイアログを飛ばしてTwitterに遷移します

1010usersがブックマークコメント88

    ガイドラインをご確認の上、良識あるコメントにご協力ください

    0/0
    入力したタグを追加

    現在プライベートモードです設定を変更する

    おすすめタグタグについて

      よく使うタグ

        ドキュメントに固執せよ - gfnweb

        ガイドラインをご確認の上、良識あるコメントにご協力ください

        0/0
        入力したタグを追加

        現在プライベートモードです設定を変更する

        おすすめタグタグについて

          よく使うタグ

            はてなブックマーク

            はてなブックマークで
            関心をシェアしよう

            みんなの興味と感想が集まることで
            新しい発見や、深堀りがもっと楽しく

            ユーザー登録

            アカウントをお持ちの方はログインページ

            記事へのコメント88

            • 注目コメント
            • 新着コメント
            sgo2
            「コンピュータが期待する動作をするコード」と「人間が期待するよう解釈する文章」では前者の方が遥かに簡単に書ける。後者は個や状況で反応が変わり過ぎる。

              その他
              tettekete37564
              コードを読めば何をやっているかは分かっても、何のために何でその実装なのかは分からない。つまり実装からその要件は分からないとという事。特にバグがあった時とかね。

                その他
                nyankosenpai
                人類の多くには言語化する力がないし、言語を読み取って行動することも苦手としているのだ。けっこうな特殊能力だと思います

                  その他
                  kaakaa_hoe
                  whatよりhow、howよりwhy、whyよりwhy not。記録残さないと後々変更する時に観点漏れるよね。

                    その他
                    hitotakuchan
                    ドキュメントのないソフトウェアは全て負債である

                    その他
                    carrier_pigeon
                    ありがたい文書。why/why not がないと困る。次の dev も困るし ops も困る。ソフトウェアは運用フェーズがライフサイクルで一番長いし、嘘があるというのは更新プロセスを定義してないだけで書かない理由にはならない。

                      その他
                      hdannoue
                      ドキュメントは、言語で標準化された事象や現象は書きやすいし、共有性も高く、利益もある。しかし、バリエーションあることや複雑な構造は記述しにくいし、読み手に伝わりにくいので、コストに見合わない。

                        その他
                        choota
                        強いエンジニアは文章も書けるし、弱いエンジニアは文章苦手。強いエンジニアはそんなに数いないので、結果文章は置き去りにされる。

                          その他
                          khtno73
                          だからSIerは要件定義書だの外部設計書だのをフォーマットにしてるわけだけど、ただ書くことが決まってるから埋めるだけ(で、大事な要件が漏れる)のSEをどうするか問題が出るわけよね

                            その他
                            roshi
                            とりあえず句読点は、。で統一して書いて欲しい。

                              その他
                              tosi29
                              “ドキュメントは「なぜつくったのか」「何を実現しているのか」「どう使えるのか」についての記述を含んでいなければならない.”

                                その他
                                enemyoffreedom
                                2022年6月の記事

                                  その他
                                  manhole
                                  “ドキュメントで何よりも先に伝えなければならないのは「なぜつくったのか」「何を実現しているのか」「どう使えるのか」である.”

                                  その他
                                  luccafort
                                  “ともすれば何が解決困難な課題だったかとかどこに工夫を凝らしたのかといった “苦労話” を詳細にしたくなってしまうけれども,そういう話を初見の読者にいきなりしても何も伝わらない”あ、はい。すみません。

                                    その他
                                    rryu
                                    ドキュメントを書かなくても評価は下がらないが、下手なものを書いたりそのせいで仕事に時間がかかったりすると評価が下がるという完全にやったもの損な状況をまず変えるべきだと思う。

                                    その他
                                    gfx
                                    “我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか”

                                      その他
                                      toritori0318
                                      良い。自分がドキュメント書くときに意識してるのは「何も知らん人が入ってきたときに質問されずにすんなりプロジェクト開発できる」ようにしてることかな

                                      その他
                                      syu-m-5151
                                      コードには How テストコードには What コミットログには Why コードコメントには Why not 。では、ドキュメントには?

                                        その他
                                        yatmsu
                                        ほんとこれ。

                                        その他
                                        kazkaz03
                                        社内wikiがよく失敗するのと同じことだと思う

                                          その他
                                          seal2501
                                          概ね同意なんだけど「why/why not」はコミットログやPRやissueにも書き込めるしVS codeで辿れるので、雑なIssue/PRをリジェクトすることから始めるのが気楽だと思ってる(ただしメンバーからは嫌われる

                                            その他
                                            takilog
                                            テレワークで人間は意外と文書書けないし読めないってのが分かってきてるから、こういうのはかなり難しいなって感想。背景目的みたいなのすら書けない、読めない事例が多数。

                                              その他
                                              bootJP
                                              Design Docっぽい “論文のAbstractとIntroductionにあたる部分が必要だと考える”

                                                その他
                                                shag
                                                最近齢10年強の古のコード読みふけってるけど、ドキュメントに why, why not を書かない人は本当に多い。そしてクッソ古いドキュメントが放置されてたり、すでに通らないコードブロックが残ってたり。

                                                  その他
                                                  pmint
                                                  それは取説でしょ。ドキュメントを知らない。文章もひどい。実務経験なさそう。この投稿をレビューしてもらうべき。必要なのは「どんな要求があったか」「どう作ったか」「なぜその手段(ロジック/UI)なのか」だ。

                                                  その他
                                                  marmot1123
                                                  大事なことは分かっているけど、ドキュメントを書くのは(読むのも)疲れる。

                                                  その他
                                                  ema_hiro
                                                  いい話。スタンスとして「固執する」くらいでちょうどいいのかもしれない。コードからは「何をしてるか?」はわかるが「なぜしてるか?」はわからないわけだし。

                                                    その他
                                                    yoiIT
                                                    “どうして人間集団はこんなにも知見の共有を円滑にできないのか? ”

                                                      その他
                                                      thaim
                                                      何言っても書かない人は書かないので、自分のために書く。ドキュメント書かずに設計できないし、1年後に自分が困るだけなので。チームで書くようになるには報酬設計から考えないといけないので大変

                                                      その他
                                                      knok
                                                      code2textは研究はされてるけど、当然ながらコードレベルの解説しか出力しない。教師データもdocstringとかだっりするし

                                                        その他
                                                        khtno73
                                                        khtno73だからSIerは要件定義書だの外部設計書だのをフォーマットにしてるわけだけど、ただ書くことが決まってるから埋めるだけ(で、大事な要件が漏れる)のSEをどうするか問題が出るわけよね

                                                          2022/06/19リンク

                                                          その他
                                                          HM_Atlas
                                                          “どうして人間集団はこんなにも知見の共有を円滑にできないのか? “ / これオブこれ

                                                            その他
                                                            kei_0000
                                                            上の立場は書かせたいけど、エンジニアは書きたくない(苦手&面白くない&自分がそこまで困らない)。レビューとか以前にまず書いてもらうことが大変。評価に含めるのもよいが、採用面談時に質問して見極めたい

                                                            その他
                                                            pascal256
                                                            確かにドキュメントに経緯や意図を書くのは大事。パラメータ値とかも理由がわからん事あって変えれなくなったりするし…

                                                              その他
                                                              dal
                                                              ドキュメント書いてもなーー読まれねえんだよなーーーほんとーーーーゴロゴロゴロそして書き手が途中でやめる。読んでくれさえすれば理解できる人たちなのにな。

                                                                その他
                                                                damasareta
                                                                これは名言。「そもそも対人コミュニケーションというものは “厖大な知的体力と時間を奪われ,ペイロードではなくメタデータの比重が大きい,デフォルトでかなりの損害をもたらす営み” だ.」

                                                                  その他
                                                                  onesplat
                                                                  6. 変化が激しすぎて書く側からoutdatedになっていくため。4. 時間が取れないの見積もりが静的で甘い、ということでもあるかもしれない。追従チェッカも技術的/UX的になんとなく非現実的そうではある

                                                                    その他
                                                                    taitoku
                                                                    コード書く以外も高度な仕事があるって事だね。

                                                                      その他
                                                                      jintrick
                                                                      抽象化能力がないと書けない。残念ながら特殊能力に近い。

                                                                        その他
                                                                        Nnwww
                                                                        包括的でいい文章!個人的には開発プロセスに明示的にドキュメンテーションとそのレビューを組み込むべきだと思っている。何らかのプログラミングには対応するドキュメントの追加or修正をほとんどの場合含むはず。

                                                                        その他

                                                                        注目コメント算出アルゴリズムの一部にLINEヤフー株式会社の「建設的コメント順位付けモデルAPI」を使用しています

                                                                        リンクを埋め込む

                                                                        以下のコードをコピーしてサイトに埋め込むことができます

                                                                        プレビュー
                                                                        アプリのスクリーンショット
                                                                        いまの話題をアプリでチェック!
                                                                        • バナー広告なし
                                                                        • ミュート機能あり
                                                                        • ダークモード搭載
                                                                        アプリをダウンロード

                                                                        関連記事

                                                                          usersに達しました!

                                                                          さんが1番目にブックマークした記事「ドキュメントに固...」が注目されています。

                                                                          気持ちをシェアしよう

                                                                          ツイートする

                                                                          ドキュメントに固執せよ - gfnweb

                                                                          どうして人間集団はこんなにも知見の共有を円滑にできないのか? 改善にはドキュメントにまつわる各個人...どうして人間集団はこんなにも知見の共有を円滑にできないのか? 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい. ここでテーマにしているのは,著名OSSなど世の中にいくらでも知見が転がっている対象ではなく,特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである. 非常に乱暴な言い方をするなら,「コードとか大部分は誰でも書けるようになるものなんよ,そんなところにマッチョイズムとか感じなくてええねん,我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3,2022 ドキュメントに書く内容の必須項目或るシステム(ソフトウェアなど)について,そのシステムのことを全く知らない人を想定読者としたドキュメント

                                                                          ブックマークしたユーザー

                                                                          • wkoichi2025/11/16wkoichi
                                                                          • tosi292025/11/10tosi29
                                                                          • Nogayama2025/09/26Nogayama
                                                                          • accelerk2025/06/24accelerk
                                                                          • oribeyu2025/03/13oribeyu
                                                                          • mayu_01212025/03/13mayu_0121
                                                                          • ularaka2024/12/02ularaka
                                                                          • enemyoffreedom2024/11/27enemyoffreedom
                                                                          • be-goodman2024/09/24be-goodman
                                                                          • gabill2024/04/12gabill
                                                                          • tetsugrande2024/02/08tetsugrande
                                                                          • sam-ple2024/01/19sam-ple
                                                                          • devorgachem2024/01/12devorgachem
                                                                          • techtech05212023/09/03techtech0521
                                                                          • Vez2023/08/16Vez
                                                                          • longyang2023/06/15longyang
                                                                          • kegelstatt2023/04/01kegelstatt
                                                                          • ni_haru2023/03/31ni_haru
                                                                          すべてのユーザーの
                                                                          詳細を表示します

                                                                          ブックマークしたすべてのユーザー

                                                                          同じサイトの新着

                                                                          同じサイトの新着をもっと読む

                                                                          いま人気の記事

                                                                          いま人気の記事をもっと読む

                                                                          いま人気の記事 - テクノロジー

                                                                          いま人気の記事 - テクノロジーをもっと読む

                                                                          新着記事 - テクノロジー

                                                                          新着記事 - テクノロジーをもっと読む

                                                                          同時期にブックマークされた記事

                                                                          いま人気の記事 - 企業メディア

                                                                          企業メディアをもっと読む

                                                                          はてなブックマーク

                                                                          公式Twitter

                                                                          はてなのサービス

                                                                          • App Storeからダウンロード
                                                                          • Google Playで手に入れよう
                                                                          Copyright © 2005-2025Hatena. All Rights Reserved.
                                                                          設定を変更しましたx

                                                                          [8]ページ先頭

                                                                          ©2009-2025 Movatter.jp