質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
質問をする技術 - くりにっき
以前社内に書いたポエムなんだけど年に1回くらい引用したくなるので公開した tl;dr; 質問をする時はゴールを提示する【MUST】 理由1 理由2 コンテキストを詳しく共有する【SHOULD】 期待してた結果(expect)と実際の結果(actual)を書く【IMO】 2020/7/22 12:30追記 2020/7/22 19:00追記 tl;dr; テンプレ 【質問内容】 【やりたいこと or 今困ってること or 質問の意図】 質問をする時はゴールを提示する【MUST】 なにかやりたい けど実現できない、うまくいかない それで質問する って感じに、質問をする動機としてまず やりたいことありき のはずなので、それを提示すべきです 理由1 質問される側（以下回答者）は質問内容がふわっとしていると色々なケースを想定して回答を組み立てます *1 例「Aの場合は～だけど、Bの場合は～」 こうい
知らない技術は怖い - Mitsuyuki.Shiiba
AよりB、CよりD 今後の方向性を決める判断の中で「Aという技術ではなくBを採用する方がが良さそうです」とか「既存システムのCは良くないからやめてDを使うようにしましょう」とか。最近、何人か全然別の人からそういう話を聞く機会があった。 AよりBが良さそう？ 「僕はAの方が良いと思うんですけど、Bの方が良さそうだと思う理由を知りたいです」って聞くと「Aはこういう部分に問題があると思います」って言われて話が噛み合わなくて、しばらく話をして気づいた。 この人、Aを触らずに想像だけで喋ってるんだ。ってことに。なので、実際に動かして見せてあげると「あぁ、それならAの方が良いですね」ってなった。 「興味があるだけなんですけど、僕も知らない技術だったので少しドキュメントを読んで実際に触ってみて機能を確認してからAの方が良いなと思ったのですが、どうして触らずに想像だけでAは問題があるって断言したんですか？
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
