HIRAKI Satoru Layzie

技術文書の書き方

このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。

科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。

しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の役に立つのではないかと考えて記します。

概要

ネットーワーク機器のマーケ担当をしてる妻から聞いた、Wi-Fiルータのオススメ（「同僚のメーカー担当ごとに己の”最強”を選んでもらった」とのこと）です
「ルーターにはWi-Fiルータだけじゃなく他にもいろいろあるんだよ！これはWi-Fiルータのことね」と言われたのでタイトルを変えました
「AXほにゃらら」は規格（AX = Wi-Fi 6）+速度の参考値とのことです
もともとの文脈: 家庭内の雑談をツイートしたところ（ https://twitter.com/__gfx__/status/1464084908091920387 ）知人が反応したので妻に「ルータのおすすめ教えてと知人がいってるのでなんか教えて」といって教えてもらったのが元です
下にあるv1.md が最初のやつ（2021/11/26）で、このv2.md がホッテントリ入りしたあとの改訂版（2021/11/27）です

追記（2022/05/24）:

TP-Linkはちょいちょいやらかしがあります

blacklist/whitelist master/slave に関する情報集め

blacklist/whitelist、master/slave という単語は相応しくないという意見に OSS がどの様に対応すべきかを自身で考える為の情報集めです。見つけ次第、逐次更新していきます。

僕(mattn) 自身は black lives matter に同意をしています。blacklist/whitelist、master/slave という単語を廃止する事が、歴史的背景を持たない文化圏では特定の意味を持たなかった為、個人的には若干思う所はありますが、廃止自身に反対するつもりはありません。

昔から、主副を表す物には master/slave という単語が使われてきました。ハードディスクの IDE、仮想端末(pty)、色々あります。またネットワークの IP フィルタリングに関しては blacklist/whitelist と表記した物が今でも沢山あります。

我々日本人が意識せずに使っていた blacklist/whitelist、master/slave という単語が、人々にどの様に影響しうるのか、今後 OSS としてどの様に関わっていけば良いかを理解する上で、自分なりの情報集めをしたいと思っています。

Git 2.26.0以下にある脆弱性

Git 2.26.0以下^＊1には、細工したリポジトリをgit cloneしたときに、そのユーザーのCredential(たとえばGitHub.comをcloneするときに使う認証情報)を奪い取れる脆弱性があります。

📝 取得できる認証情報は credential.helper の設定に依存する

既にPoC(検証するためのコード)もあり、結構簡単なので是非Gitを2.26.1以上にアップデートしましょう。 git submoduleを使うと見た目ではわかりにくい攻撃もできるので、「気をつける」では回避は難しいです。

2020/5/31追記: 自分用のメモに書いていたつもりだったのですが、たくさんのスターを頂けてとても嬉しいです。
と同時に、書きかけで中途半端な状態のドキュメントをご覧いただくことになっており、大変心苦しく思っています。

このドキュメントを完成させるために、今後以下のような更新を予定しています。

TODO部分を埋める
書籍を基にした理論・原則パートと、実装例パートを分割
- 現在は4層のレイヤそれぞれごとに原則の確認→実装時の課題リスト→実装例という構成ですが、同じリポジトリへの言及箇所がバラバラになってしまう問題がありました。更新後は、実装時の課題リストを全て洗い出した後にまとめて実装を確認する構成とする予定です。

2021/1/22追記:

Use the following to generate gemset.nix:

nix run nixpkgs.bundix --command bundix

Then run:

nix-shell

How to Change Open Files Limit on OS X and macOS

This text is the section about OS X Yosemite (which also works for macOS Sierra) from https://docs.basho.com/riak/kv/2.1.4/using/performance/open-files-limit/#mac-os-x

The last time i visited this link it was dead (403), so I cloned it here from the latest snapshot in Archive.org's Wayback Machine https://web.archive.org/web/20170523131633/https://docs.basho.com/riak/kv/2.1.4/using/performance/open-files-limit/

	const forceDeleteDB = async (name: string) => {
	if (!("databases" in indexedDB)) {
	return;
	}
	// @ts-ignore
	const dbs = await window.indexedDB.databases();
	const deleteDB = (name: string) => {
	return new Promise((resolve, reject) => {
	const transaction = window.indexedDB.deleteDatabase(name);
	transaction.addEventListener("success", () => {

	(function(c,b,cs,r,d){
	b.frameBorder=0;
	b.style = 'position:fixed;bottom:0;left:0;width:100%;height:30vh;background:#fff;border-top:4px solid #bbb;box-shadow:0 0 2px #000;z-index:999;cursor:ns-resize;';
	b.onpointerdown=function(e){b.setPointerCapture(e.pointerId);b.e=e;b.h=b.offsetHeight-4;b.style.borderTopColor='#59f'}
	b.onpointermove=function(e){if(b.e)b.style.height=(b.h-e.y+b.e.y)+'px'}
	b.onpointerup=function(){b.e=null;b.style.borderTopColor='#aaa'}
	document.documentElement.appendChild(b);
	(d=b.contentWindow.document).open();
	d.write('<style>html,body{width:100%;height:100%;overflow:hidden;font:12px/1.2 system-ui,sans-serif;flex:1;display:flex;flex-direction:column;margin:0;}*{box-sizing:border-box;}button{font:inherit;}pre{margin:0;padding:4px;border-bottom:1px solid #ddd;}</style><div style="background:#ddd;border-bottom:1px solid #ccc;display:flex;padding:3px 5px 4px;align-items:center;"><div style="color:#555;flex:1;">Console</div><button onclick="console.clear()">clear</button></div>

	name: XXXX
	attributes:
	LastUpgradeCheck: 1140
	ORGANIZATIONNAME: "kankak, Inc."
	options:
	bundleIdPrefix: com.xxxx.xxxxxxxx
	deploymentTarget:
	iOS: 13.1.3
	configs:
	Develop Debug: debug

HIRAKI Satoru Layzie

技術文書の書き方

概要

blacklist/whitelist master/slave に関する情報集め

Git 2.26.0以下にある脆弱性

How to Change Open Files Limit on OS X and macOS

Mac OS X

To check the current limits on your Mac OS X system, run: