本ブログの記事作成時の方針
About
- 当ブログ内で記事を書く際の方針やスタイルをメモする場所です
- 文章を書く際のコード規約に近い何か
Rules
1. コンテンツ
記事を書く際は、読者を想定し、以下が伝わることを目的に書く。
- どんな問題を解決するために、何について話をしようとしているのか？
- 解決策の概要
- それがあると何が嬉しいのか？
- 抽象度の高い概念については、具体例も示す
特定のプロダクトについて説明をする際は、以下について説明することを心がける。
- いつ誰が開発したのか。元になっている要素技術、論文 (歴史)
- どのような問題を／どうやって解決しようとしているのか？それがあると何が嬉しい？
想定されるユーザーとユースケース
- できれば、単に特定のユースケースを語るのではなく、「どういう開発(運用)体制/分業体制下でどのような業務の全体図があって、その中で誰が使うといいのか？どのような効果が期待できるのか」まで踏み込めるといい。ユースケース図を書きながらアクターを整理するイメージに似ている.
機能について説明する際は、「直接的に何をしているのか？(石を積む)」だけでなく「それにより上位のどのようなことが実現されるのか？(城を作る)」についても説明する
- 設計思想/トレードオフ構造についてどのような意思を表明しているのか？
- 参考文献の一覧
- より詳細な情報を知りたい時の道標を提供する
2. 全体の構造
- 以下で言われているような構造を目指す
2.5 荒く文章をプロトタイプする時の方法論
- 以下の順番で書き進める。
- まず書きたいことを殴り書きする
- 次に上記に従い、付属する部品を補完しつつ再構成する
- 時間がない時は、一旦箇条書きスタイルでもokだが、後で「文」に置き換えることを心がける
3. スタイル
- 課題と解決策がペア/ワンセットになるような説明を心がける
- 段落の中には、同じような話題を扱った文が凝集している状態を目指す。仲間はずれの文を見つけたら、他の段落への引っ越しを検討する
4. 記法
- 「である」調ではなく、「ですます」調で書く
- 読者に適切に説明するために記事を書く、という意識づけのため
- 用語については、できるだけ和名と英名を併記する
- 例: × 冪等性、○ 冪等性(idempotency)
- 丸括弧を使うときは、丸括弧の前後に半角スペースを入れる
- 例: × データ(Data)の活用、○ データ (Data) の活用
- ひらがなにした方が読みやすい単語についてはひらがなで記載する
- 例: × 全て、更に ○ すべて、さらに
- 引用文献を記載する時は、はてなの脚注記法を使う
- (())
- 長めの文章を書く際は、H要素にナンバリングをして、contentで目次を自動出力させる ※ サンプルとなる過去記事
お手本とする記法
特定の概念をコンパクトに説明する記事としては、以下記事の書き方がきれい。参考にする。 www.codereading.com
英文のパラグラフライティングを意識した文章としては、以下の記事の文章が優れている。 https://www.joyent.com/node-js/production/design/errors
