Posts

1.この記事を書こうと思った背景 ぼくはリモートワークで仕事をすることがほとんどだ。リモートワーク下において仕事でのコミュニケーションの大半は テキストベース だが、文章で自分の考えを伝える ことのむずかしさを感じることが多々あった。そうした背景がありつつ、以前読んで読みやすいと感じた『プログラマの数学第2版』や数学ガールシリーズの著者が 『数学文章作法 基礎編 （ちくま学芸文庫）』(以下、本書)を出版しているということで手に取った。本書から学んだことを、ここに書き留めておく。 2.目次 第1章　読者 第2章　基本 第3章　順序と階層 第4章　数式と命題 第5章　例 第6章　問いと答え 第7章　目次と索引 第8章　たったひとつの伝えたいこと 3.本書を通しての学び よい文章を書くことはむずかしいと改めて感じる一方で、じゃあ、どうすればいいか？そのヒントを得ることが出来た。そのヒントを章ごとに挙げていく。 「第1章　読者」より 読みやすい文章を書く 著者は読みやすい文章を書く原則とは、読者のことを考える ことだという たしかに文章を読もうと手にとってもらわなければどんなにいい文章でも意味がない では、読者のことを考える とは何について考えればよいのか？というと、著者は以下の3点を挙げている 読者の知識 読者の意欲 読者の目的 書こうとしている文章は読者の知識レベルに配慮して書かれているか。文章を読み進めようという意欲を掻き立てるものか。読むことで自分の目的は満たされると思ってもらえるか。どれも抜け落ちていた視点だったので、本書を読み進めようという強いモチベーションに駆られた。（しばらく読み進めて、なるほど。これが読みやすい文章かとなった。） また、本書では述べられていなかったが、会社やコミュニティなど書き手と読み手が共通のコンテキストを有する場合には、過去に積み上げられてきたドキュメントから文章の書き方や、そこで使われているローカルルールを押さえておくと、読者にとって読みやすい文章を書く助けとなるだろうとも感じた。 「第2章　基本」より 文は短く これは、何を主張している文か と自問自答 逆説ではない「が」を使い、冗長的になっていないか？ 「ちなみに」と、本筋からはずれているとはいえ、理解の助けとなる話題を提示しているか？ 「第3章　順序と階層」より 書き直しの重要性 書き直しをすることを想定して書き始めるべき 接続詞は使わず、箇条書きで書くことはせずとも、キーフレーズを書き並べるところから始めるだけでもいいかもしれない 「第4章　数式と命題」より あいまいさをなくす ひとつの文章ではひとつのことを伝える 「第5章　例」より 例のファーストチョイスは、典型的なもの その次に極端な例や、あてはまらない例、一般的な例などが続く 例を挙げる際にも、読者の知識レベルやバッググラウンドに配慮すること OSS やクラウドベンダーのドキュメントでよく出てくる Getting Started は典型的な例にあてはまるのだろう。 4.なぜ、よい文章を書くことはむずかしいのか よい文章を書くことはどうしてむずかしいのか。本書を読みながらこの理由について考えていた。 ひとつ挙げるとすれば、やはり書き手と読み手の知識レベルやバッググラウンドにギャップがあることではないだろうか。 だからこそ、読者のことを考える 、つまり、読み手の知識、意欲、目的に関心を持つこと がよい文章を書くうえで、もっともだいじなのではないか。よい文章を書くということは一朝一夕にできるものではないけれどコツコツと続けてモノにしたい。

1.この記事を書こうと思った背景 Terraform の description に複数行書きたいとなったので調べた。また、p.s. に description について分からなかったことも書き留めておく。 2.やりかた Heredoc Strings | Strings and Templates - Configuration Language | Terraform by HashiCorp を読むと、ヒアドキュメント を使うとよさそうだ。 variable の description に使ってみる。 variable "instance_types" { description = <<-EOT 検証用なのでできるだけお金をかけないようにしている。 大きいサイズは、t3.xlarge などがある。 https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes EOT default = ["t2.small", "t3.small", "t2.medium"] #default = ["t3.xlarge", "t3.2xlarge"] } 3.小ネタ)EOT としているワケ Terraform のドキュメントのサンプルコードにおいて、EOT としているのは、end of text の意味を込めているからだという。 In the above example, EOT is the identifier selected. Any identifier is allowed, but conventionally this identifier is in all-uppercase and begins with EO, meaning “end of”....

1.この記事を書こうと思った背景 『プログラマの数学 第2版｜結城浩』(以下、本書)を読んだ。本書から学んだことを、ここに書き留めておく。 2.目次 はじめに 第1章 ゼロの物語 ―― 「ない」ものが「ある」ことの意味 第2章 論理 ―― trueとfalseの2分割 第3章 剰余 ―― 周期性とグループ分け 第4章 数学的帰納法 ―― 無数のドミノを倒すには 第5章 順列・組み合わせ ―― 数えないための法則 第6章 再帰 ―― 自分で自分を定義する 第7章 指数的な爆発 ―― 困難な問題との戦い 第8章 計算不可能な問題 ―― 数えられない数、プログラムできないプログラム 第9章 プログラマの数学とは ―― まとめにかえて 付録1：機械学習への第一歩 付録2：読書案内 3.本書全体を通しての学びや感想 ものごとの構造を見抜き、一般化する 本書は 「ものごとの構造を見抜き、一般化する」 ことについて、その大切さと方法論について事例を交えて紹介されている。 そのアプローチの一例としては、たとえばものごとを小さくみること、あるいは2分割や再帰性を見出すことなど。 読みやすい印象を抱いたこととそのワケを考える また、とても読みやすい印象を持った。 なぜ、このような印象を抱いたのか？ それは、独自の見解を提示する前に既知の話題や身近な関連事例を提示しているからではないか？と思う。本書は、話し手がもっとも言いたい独自の主張を読み手に伝えるためのエッセンス集であるともいえるかもしれない。 さて、章ごとの読書メモを書いていたのでそちらも共有しよう。(ただし、7章以降を除く。) 4.章ごとの読書メモ 「第1章 ゼロの物語 ―― 「ない」ものが「ある」ことの意味」 「ない」ことを表現する難しさと大切さ。 e.g. 位取り cf. 意外と知らない「ゼロ」の持つ意味と概念―あなたも「ゼロ」という数字から、知的探求、始めてみませんか？－　|ニッセイ基礎研究所 「第2章 論理 ―― trueとfalseの2分割」 物事の論理は、章の副題にも挙げられている 2分割 を意識すること。また、複雑な表現は論理式の考え方を使うとシンプルになることがあるということ。...

1.この記事を書こうと思った背景 今更感満載だけれど、パッケージの依存関係の更新ツールである Renovate について理解が浅いと感じることがあった。とりわけ、Presets や Config の書き方については見様見真似でやってしまっている感が否めなかった。 そこで、表題のとおり、Renovate を個人リポジトリで小さく始めながら 、Renovate を触っていく上で押さえておきたい点について、この記事に書き留めていきたい。 2.前提と環境情報 Renovate の platform は https://github.com とし、GitHub App で運用する。Renovate の導入手順は Installing & Onboarding - Renovate Docs を参考にした。 また、Renovate で指定する更新方法のことを Config と書いておく。というのも 設定 と日本語で書いてしまうと一般的な「設定」と、Config のうち、どちらを指して書いているのか、区別することが難しいためである。 3.スタート地点としての [“config:base”] Renovate の Config は 設定ファイルに書いていくのだが、公開されている Presets(Config Presets) を使うこともできる。 たとえば、Shareable Config Presets - Renovate Docs | Renovate Docs で紹介されている、extends: [“config:base”] を指定するだけでも Renovate を使うことができる。 $ cat renovate.json5 { extends: ["config:base"], timezone: "Asia/Tokyo" } ※ renovate.json5 はコメントが書ける renovate....

0.この記事の結論 pcasteran/terraform-graph-beautifier: Terraform graph beautifier が個人的にはおすすめ！やはり、Terraform にビルトインされた terraform graph を input 値としているせいか、安定している印象を受けた。 im2nguyen/rover: Interactive Terraform visualization. State and configuration explorer. もとくにビジュアル面でよかった。ただし、Docker で扱う場合、Docker ホスト側の Terraform のバージョンによってはうまく動かないことがあったので、2番目におすすめとしたい。 1.この記事を書こうと思った背景 terraform graph という Terraform のリソース可視化ツールがある。これは Terraform にビルトインされたコマンドのひとつであり、Terraform で表現するインフラリソースの可視化ツールのひとつである。 詳細な使い方は以下の Terraform のドキュメントを参照してほしい。 Command: graph | Terraform by HashiCorp そんな terraform graph だが、リソースが多いと見にくいという欠点がある。そこで、表題のとおり、terraform graph よりビジュアライズな Terraform のインフラリソース可視化ツールを探すことにした。 1-1.可視化する Terarform のサンプルコード 今回、可視化する Terarform のサンプルコードは、以下の「7.サンプルコード」で書いているものとする。 7.サンプルコード | 複数の AWS Lambda のエラーを CloudWatch Alarms で検知できるように Terraform で定義する | gkzz.dev...