セミナー参加ログ》技術文章の品質を上げるヒント 2020/12/21(月) 19:30 〜 22:00
技術書界隈を盛り上げる会 年末スペシャル回 「技術文章の品質を上げるヒント」YoutubeLive ライブ配信セミナーを聴講した時のメモ。
登壇者本人が話した内容に限らず、後から調べたことや感想も混じっているので注意。
- 技術文章の品質を上げるためにやってきたこと @ariaki4dev
- 『数学文章作法』で、わかりにくい文章をビフォーアフターしてみよう @llminatoll（湊川あいさん＝わかばちゃんの人）
- 初めての技術書執筆を通した失敗談 @kuwahara_jsri
- 明後日からできる読みやすくするテクニック @sour23 大沢さん（テクニカルライター）
- TVと蝿でテレビバエ！ブログはデストロン怪人の精神で書け！ @shigetaka256 （小笠原種高さん）
- 質疑応答型 座談会タイム
- 気付き（3つ書く）
技術文章の品質を上げるためにやってきたこと @ariaki4dev
- 1年ごとにチームの予算編成
- 四半期ごとにOKR。
- 「OKR」は知らない言葉だった。Objectives and Key Results（目標と主要な結果）の略称で、「最終目標を達成するための道のり（プロセス）」をチームで共有したり、「見える化」したりする目標の設定・管理フレームワーク。
- OKRとは？ 【Google、Facebookが使う目標管理ツール】KPI・MBOとの違い、導入・運用・目標設定方法について解説 - カオナビ人事用語集
- Objectives（目標） 定性的な、シンプルで覚えやすく、1〜3ヶ月で達成可能な目標であること
- 全体を通して共通の表現にし、それを継続的に呼びかけ続ける。アウトプットテーマの「選択と集中」。
『数学文章作法』で、わかりにくい文章をビフォーアフターしてみよう @llminatoll（湊川あいさん＝わかばちゃんの人）
- 結城浩さんの『数学文章作法』→ 解説文を書くときにすごく参考になる。基礎編と推敲編がある。
- わかりやすい文章とは
- 読点をうつ。
- 順番を変える。「寄ってきたリスに、私はカメラを抱えたままくるみをあげた。
- 複数の短い文に分ける。「リスが寄ってきた。私はカメラを抱えたまま、そのリスに
- では次に、バックアップなどのような機能について解説します。
- 無駄な次に、バックアップについて解説します
- 正確性を担保したいがために「〜などのように」を多用してしまう。
- → 早く・重く答える。
- 初心者読者相手に、正確だがわかりづらい文章を提示しても飲み込めない
- 長文は読み手に負担がかかる
- 『数学文章作法』はセミナー後に購入して読み中。平易な文章でとてもわかりやすい。本の構成もよく練られており、この本自身が、わかりやすい文のお手本集になっている。この手のジャンルでバイブル的な存在といえば『理科系の作文技術 (中公新書 著:木下 是雄)』があるが、私には 理科系の〜の方はお堅い印象でいまひとつ頭に入らなかった。今回のセミナーで良い本を紹介してもらって良かった。
- マンガの何気ないセリフも、読み手にあわせて文の長さや切り取り方を考えて作り込まれているのがわかった。湊川さんが普段から地道にアンテナを張って「わかりやすさ」向上の努力をされていることが感じられて頭が下がる思いがした。
- 作者:結城 浩
- 発売日: 2014/12/12
- メディア: 文庫
初めての技術書執筆を通した失敗談 @kuwahara_jsri
- GitBook
- markdownで書ける執筆ツール。クラウドサービス
- gitbook-cli
- npmでインストール
- gitbookで設計書を作成したら最高だった話 - フォトシンス エンジニアブログ
- 製品（コード）をしっかり書いてから、執筆する。同時進行しないのがポイント。
- 曖昧な表現よりも、具体的な方がわかりやすい。
- 誤字脱字チェッカー textlint
明後日からできる読みやすくするテクニック @sour23 大沢さん（テクニカルライター）
- Mofukabur（モウフカブール） 明後日シリーズの人
- 読みやすくするテクニック
- 構成企画
- 丁寧に
- スタイル・ルールに従う
- 丁寧に
- 前提を書く 環境、揃えるもの
- 技術書
「ここでは、こう定義します」「例としてxxする」と書く- 決まり事なら原典を提示する
- 「多くの場合は」「慣例では」「著者のプロジェクトでは」
- 著者の周りのローカル言語は初出時に明記する
- スタイル・ルールに従う
- 慣例に従う、型に従うことで読みやすくなる
- 【逆三角形】結論 - なぜなら - 補足
短く伝えたい時に、有用。
新聞・雑誌はこの展開方法 - 文言の統一
読者が混乱するので、同じことを別の文言で言わない - ひらがな・カタカナ・漢字の使い分け
公用文における漢字使用等について（内閣訓令）
実際には「記者ハンドブック」を使う- ルールは参考であって絶対ではない。
- 言い換え
- 色々 → さまざま
- することができます → できます
- 「行う」って言わない。ex.) 設定を行います、設定を行うことができます → 設定します、設定できます
- なります → 状態が変化するか？しないなら別の言い方にすべき
- 長い文と句点
- 句点を入れる
- 語順を入れ替えて句点
- プロのライターさんならではの真実味というか凄み?! を感じて恐れ入った。
TVと蝿でテレビバエ！ブログはデストロン怪人の精神で書け！ @shigetaka256 （小笠原種高さん）
- 『図解即戦力 Amazon Web Servicesのしくみと技術がこれ1冊でしっかりわかる教科書』 の人。この本は感動的に読みやすかったので印象に残っている。知らずに受講したが、話を聴けてラッキーだった。
- Mofukabur（モウフカブール） の人。
- ブログの話
- ブログは情報発信媒体の一つ
- 発進媒体には種類がある。情報の種類にも種類がある。
- コア情報は 書籍や公式サイト
- 周辺情報（コツや感情）はコミュニティ、ユーザブログ、SNS。
- 両方揃うと読者は「腑に落ちる」
- ブログでは発信するものは何か。
- 公式ブログ → コア情報 、ユーザブログ → 周辺情報
- 自分がなんの情報を載せるつもりなのか、意識することが大事。
- 芝居と小説の違い
- 技術ブログ
- 情報が早い
- 1記事が短い、隙間時間に読まれる。 結論を先に。
- 無料
つまらなければ去る。冒頭でグダグダしない。 - 検索でリーチ
タイトルや見出しを工夫する - PCやスマホで読まれる
紙とWebでは文章が違う。短文をテンポよく積み上げる
- にゃごろうさん
- ブログで大事なこと
- テレビ + ハエ = テレビバエ。情報 + 表現 = 技術ブログ
- 図解即戦力 Amazon Web Servicesのしくみと技術がこれ1冊でしっかりわかる教科書
質疑応答型 座談会タイム
- 文章の違和感に気づくコツ
- 一晩寝かせる
- ペルソナ立ててみる
- 実在の人を読者として想定して書く
- モチベーション持続 - 万里の長城作戦
できるところを作り、埋めるように進める。 - お悩み相談: カッコ書き補足が多くなってしまう。
- その補足、”今”必要ですか？
- 文章を分ける、別の記事に分ける、書く場所を分ける
- メモ、ミニコラムに吐き出す
- 次の文章として成り立たせる
- カッコで書くような内容はうるさい人向け。脚注に吐き出す
- 明後日から何を始めますか？
- マインドマップでひとり連想ゲームしてみる
- ブログで宣言しちゃう
- ラフを書き殴る
- やってみたいことを呟く。他の人が拾ってくれて実現するかも
