こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼

はじめに スタンフォード大学の John Ousterhout 教授が執筆された “A Philosophy of Software Design”(以下 APoSD と略す) という書籍をご存じでしょうか？ 書籍のタイトルを直訳すると、「ソフトウェア設計の哲学」となります。書籍の内容はまさに、ソフトウェア設計について扱っています。 本書籍をベースに、「A Philosophy of Software Design を30分でざっと理解する」というお題で社内ランチ勉強会が開催されました。本記事執筆者である岩瀬(@iwashi86)が発表者であり、勉強会資料は以下のとおりです。 スライド P.4 に記載したとおり、本書籍は John Ousterhout 教授の意見が強く反映されており、ソフトウェアエンジニアであれば、議論を呼ぶ箇所があります。実際、勉強会の実況Slackでは、「これはどうな

Transcript 1 ΠϯγσϯτϨεϙϯεΛࣗಈԽͰࢧԉ͢Δ�� 4MBDL�#PU�ͰਓػҰମͳηΩϡϦςΟରࡦΛ࣮ݱ͢Δ� (.0ϖύϘ�ҏ౻༸໵� $MPVE/BUJWF�%BZT�5SBDL�#����������������20-18:00 2 ҏ౻༸໵�͍ͱ͏�ͻΖ΍� �!IJCPNB� �� ॴଐ��(.0ϖύϘ�ηΩϡϦςΟରࡦࣨ� ࡏ৬��೥໨ �BU�ಢ໦ݝಹਢԘݪ� ৬Ґ��ϓϦϯγύϧΤϯδχΞ� ಘҙ��-JOVY�௿ϨΠϠʔͷτϥϒϧγϡʔςΟϯά� ϒϩά���ٕज़ΤϯτϦ 2 ΠϯτϩμΫγϣϯ: ൃදऀͷ঺հ https://github.com/hiboma/hiboma https://hiboma.hatenadiary.jp/ 3 (.0ϖύϘ�ηΩϡϦςΟରࡦࣨͷϛογϣϯ� ΠϯτϩμΫγϣϯ:ηΩϡϦςΟରࡦࣨͷ঺հ ग़య: Co3Ͱ

Kernel/VM探検隊はカーネルや仮想マシンなどを代表とした、低レイヤーな話題でワイワイ盛り上がるマニアックな勉強会です。佐伯氏は、WebAssemblyのWebの外の応用について発表しました。全2回。前半は、Wasmがアツい理由とデザインゴールについて。 今回のテーマは「Kernel/VM的WebAssembly入門」 佐伯学哉氏（以下、佐伯）：佐伯が『WebAssemblyのWeb以外のこと全部話す』というタイトルで発表します。 まず、WebAssemblyとは何ぞや？　という一般的な話なのですが、「Wikipedia」からの引用によれば、「Webブラウザーのクライアントサイドスクリプトとして動作する低水準言語である。ブラウザー上でバイナリフォーマットのかたちで実行可能であることを特徴とする」とあります。 実際の応用例としては、WebでGoogle Meetの背景ぼかしに使われていた

These design patterns are useful for building reliable, scalable, secure applications in the cloud. Each pattern describes the problem that the pattern addresses, considerations for applying the pattern, and an example based on Microsoft Azure. Most patterns include code samples or snippets that show how to implement the pattern on Azure. However, most patterns are relevant to any distributed syst

Interview Part 3 On July 30, 2021 Tim Dodd received a tour of Starbase with SpaceX CEO, CTO, and founder Elon Musk. This article includes key takeaways from the over two-hour-long interview. Manufacturing: Musk once again emphasized that manufacturing is underrated and design is overrated; developing a production system is 10-100 times harder than designing the product, which according to Musk, pr

今日も前回に引き続きデータベース設計の話をする。今回の話で一旦データベース設計については筆を置くつもり（ブログ書いてないで原稿書けよ＞俺）であるが、その前に話をすっきりさせて置きたいと思う。最後を飾るテーマはIDの設計である。 数字しかないのに意味を含んだID前回のエントリを見ていただいた方から、次のような構造を持った学籍番号があるというフィードバックを頂いた。 全部数値で"入学年度下2桁"+"学科コード"+"学科内のあいうえお順の順位" このようなルールで割り当てた学籍番号を、単なる数値として扱うのであれば大きな問題はない。これは数値しか含まれていないので、SQLのデータ型としては単に数値型を使えば良いだろう。だが、学籍番号から入学年度を判断する、あるいは学科を判断するといった用途で使われるのであればやはり適切ではないといえる。リレーショナルモデルの観点だけからではなく、IDとして適切で

いささか刺激の強い題名は日経クロステック編集部が付けてくれたものだが若手のエンジニアを批判する意図はまったくない。題名にある「若手エンジニア」はかつての私だからである。 50代に突入した現在の私は、いわゆるWeb系企業に所属し、業務システムを含むバックエンド領域の設計と開発に従事している。もともとはPCのデスクトップアプリケーションを開発するプログラマーとして仕事を始め、途中から業務システムの設計・開発に移った。そのとき若手エンジニアであった私は「業務システムになぜRDB（リレーショナルデータベース）が必要か」、よく分からなかった。 RDBを使いこなせなかったわけではない。業務システムを使う利用者から要求を聞き、画面をつくる。部署によって要求は異なるから複数の画面ができる。画面で入出力されるデータ項目を集め、正規化してRDBにまとめ上げることはやれていたし実際につくった業務システムはきちん

みんな大好きImageMagickは、入力画像のデフォルトの色空間はsRGBだとみなす一方、各種の画像加工のオペレータは対象となるデータの色空間がRGBであることを前提としている。したがって、色空間を明示的に変換しないで処理を行うと結果がおかしなことになるのだ。本家の記事にも書いてあるが、たとえリサイズであっても色空間の影響を受けてしまう。 リサイズを「convert old.jpg -resize 400x300 new.jpg」とかやるように書いているサイトが多い。それも間違いではないが、最適ではない。これからは「convert old.jpg -colorspace rgb -resize 400x300 new.jpg」ってやってほしい。 人間の視覚の特性として、暗いところの輝度の差には敏感だが、明るいところの輝度の差には鈍感だというのがある。暗い部屋で豆電球を点けると明るさが分か

「そのほうが語って聞かせるレースをことごとく観戦する暇が、いつそのほうにあったのか不思議なことよ。そのほうはこのコロナ渦、一歩もスマホの前から動いた様子さえないように朕には思えるのだが。 」 「私が見、またおこなうことはすべてこのスマホ画面と同じ静謐、同じ薄明、また同じネイチャのささやき*1渡るこの静寂が支配する精神の空間において意味を得るのでございます。恐らく、この世界で残されているものはジュエルと金を永遠に吸いこみつづける巨大な虚無と、ウマたちが戯れ遊ぶサークルのミニキャラ画面だけでございます。この二つの場所を距てているのはわれらの瞼でございますが、そのいずれが内にあり、いずれが外にあるかは、だれにもわかりません。」*2 「して、そのほうはこの一月でどれほどのウマを育てたのだ」 「200」 「200」 200のウマがあり、200の生があり、200の死があった。*3 あれのような名馬だけ

はじめに やめろ、ではなく、やめたほうがいい。です。自分のユースケースに合ってるか今一度確認することを推奨します。基本的にはAlpineは避けたほうが良い、というのが2021年時点での私の認識です。 なんで？ libcに一般的な互換性が不足しているからです。Ruby、Python、Node.jsなどでNativeモジュールをバンドルしているアプリケーションの場合、パフォーマンスの劣化や互換性の問題にぶち当たる場合があります。 superuser.com あとは他のベースイメージの軽量化もそれなりに進んできていて、Alpineが定番軽量イメージと言う認識は2018年頃には消えつつあったかなという認識でいます。 どうすりゃええねん ※Debian Slimがあるやんってツッコミ結構もらったんですが、Slimは当たり前過ぎてもう紹介しなくていいかなっていう甘えで省略していました。よろしくおねがい

https://gyazo.com/56264d518cb334770c577d7f08824eec https://twitter.com/notainc_jp/status/1368748505016102913

サイト信頼性エンジニアリングと DevOps の関係については、よく寄せられる一連の質問があります。たとえば、どのような点が同じでしょうか。 これらはどのように違うのでしょうか。 組織内で両方を使用することはできますか、などです。 この記事では、この関係について理解を深めるために、SRE および DevOps コミュニティによって提供されている回答の一部を共有します。 SRE と DevOps は両方とも、次のような課題に対応するために作成および開発された最新の運用プラクティスです。 運用環境と開発プロセスの複雑さの拡大 それらの環境の継続的な機能性に対するビジネス依存関係の増大 これらの環境の規模に合わせて、労働力の規模を直線的に拡張できない 運用上の安定性を維持した状態での、より迅速な移行の必要性 どちらの運用プラクティスでも、監視または観測、自動化、ドキュメント化、共同作業ソフトウェ

これは マンション光配線の方式別になぜ速度が出ないのか？を解説する資料 配線方式によって天地の差が出るマンションタイプの回線を、できる限り快適に利用したい人向けの情報 付随情報として、J:COMとかのCATVの話や、UCOM光とかBB4Uとかのマンション共有インターネットの話も載せておく 想定すべき前提知識 フレッツ光やauひかりの分岐数は方式に関わらず 1収容 あたり 最大で 32 回線 となる 光配線方式はGE-PONの仕様上、どの事業者でも最大分岐数は32分岐となる NUROの採用するG-PONは規格上の最大分岐数は64~254となっているが、実際の運用は資料がないのでわかりません NTT の シェアドアクセスを利用している以上、8以上、8の倍数(8, 16, 24, 32, .... )分岐されていることは想像できる わかりやすく解説するために、実際の配線と異なる箇所がある1 電電