タグ

関連タグで絞り込む (3)

タグの絞り込みを解除

技術文書に関するopen_your_eyesのブックマーク (4)

  • 質の高い技術文書を書く方法 - As a Futurist...


    大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる1枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
    質の高い技術文書を書く方法 - As a Futurist...
    open_your_eyes
    open_your_eyes 2021/01/28
    tl;dr　わかり易く伝えたいことを明確にして書け
    リンク

  • https://www.industrialempathy.comhttps//www.industrialempathy.com/posts/design-docs-at-google/

    open_your_eyes
    open_your_eyes 2020/07/24
    設計ドキュメントの重要性
    リンク

  • テストの説明に安易に「正しく」とか書かない - Object.create(null)

    みなさんテストは書いていますよね. 書いていなければふりだしに戻る. 例えば関数 add に対して, 以下のようなテストコードがあるとします. describe("add", () => { it("正しく計算できる", () => { expect(add(1, 2)).toBe(3); }); }); よさそうですね? もしよくないと思うのであればここから下は読まなくても大丈夫なくらい理解している方だと思います. 続いて関数名を変えただけのこちらをどうぞ. describe("sub", () => { it("正しく計算できる", () => { expect(sub(1, 2)).toBe(3); }); }); なんだか明らかに間違っている気がします. もしこのテストが通過してしまったとき我々はどうすればよいのでしょうか. 考えられるパターンは 2 つあります. 実装もテストも正

    テストの説明に安易に「正しく」とか書かない - Object.create(null)
    open_your_eyes
    open_your_eyes 2020/07/24
    『正しく』と書かれた仕様書やテスト記述があると『この正しくについてはどこに記載がありますか？』と質問してしまう
    リンク

  • わかりやすい技術文章の書き方


    誰が読むのか。 読み手にどんな感想を持ってもらいたいか。 読み手はどれくらいの予備知識を持っているか。 読み手はどんな目的で、何を期待して読むのか。 読み手が真っ先に知りたいことは何か。 レポート・論文とは何か 問いが与えられ、または自分が問いを提起し、 その問題に対して明確な答えを与え、 その主張を論理的に裏付けるための事実・理論的な根拠を提示して、主張を論証する。 標準的な構成要素とは何か レポート・論文の構成は、 概要 序論 本論 論議 という要素が標準的である。次にそれぞれの要素について簡単に見てみる。 概要 論文全体を結論も含めて、すべて要約する。 序論 本論で取り上げる内容は何か。 その問題をどんな動機で取り上げたのか。 その問題の背景は何か。 その問題についてどんなアプローチを取ったのか。 本論 調査・研究の方法・結論 論議 自己の議論・結論を客観的・第三者的に評価する。 そ
  • 1

お知らせ

もっと読む

公式Twitter

  • @HatenaBookmark

    リリース、障害情報などのサービスのお知らせ

  • @hatebu

    最新の人気エントリーの配信

はてなブックマーク

公式Twitter

はてなのサービス

  • App Storeからダウンロード
  • Google Playで手に入れよう
Copyright © 2005-2024 Hatena. All Rights Reserved.