技術文書をソフトウェア開発する話

[azu]

目的

• 技術文書がもっと気軽に書けることを伝える
  • GitBook
  • textlint
• 技術文書の間違いを減らすのは才能じゃなくてテスト
  • テスト
  • CI
• ブログ以上の技術文書における設計
  • ブログぐらいのサイズだと適当に書いても問題ない
  • 技術書とかを書こうと思うと、表記が揺れたり、モジュール化されなくて管理できなくなったりする

文章のレビューが目視によるものだけという前にもっと自動化出来ることがあるという話

内容の流れ

• JavaScript Plugin Architectureでやってる事ベースの話
• ブログを校正する自動化について
• このスライドもGitBookで書かれているという話

具体的なものじゃないとやっぱり書きにくいという事が分かったのでMarkdownで書く電子書籍開発環境ベースで移行

[azu]

失敗談

• 文章のコードカバレッジを取る試み

[azu]

ドキュメント生成 documentationjs

[azu]

https://twitter.com/azu_re/status/651392711291858944

textlintと文章の品質は関係ない話

[azu]

• 校正支援はルールベース
• 推敲支援はビジュアライズベース

via d9-4.pdf

この話は校正支援のルールであるので、文章のわかり易さといった品質とは別基軸であるとかんがえられる

[azu]

GLOSSARY.mdを使ってその単語が使われる所以前で解説されているかをテストする

= referrece test

[azu]

JupyterやRMarkdownのようなREPL文章も欲しいな

[azu]

校正と推敲違いを調べる

[azu]

HTMLは元々ドキュメント向けであった話。
XHTMLみたいにセマンティックを文章に埋め込んでいくスタイルはツールに取って優しいが、
XHTMLを書く人が今は少なくなったようにそれは一般的な道ではなかった。

このテーマの人は、もっと手軽に書く電子書籍 なのだから、文章自体にセマンティックを埋め込んでいく方向とは異なるはず。HTMLのように何となく書けて、こう書くともっとツールが上手く働くのでこう書いていきたいというモチベーションを上手く持っていくような形であるべきだと思う。

GLOSSARY.mdを普通に書く人は設定が好きな人とかの一部なので、GLOSSARY.mdを書くモチベーションをあげるためにGLOSSARY.mdを使ったテストが出来るとかそういうのがあるとセマンティックを文章に導入しやすい

技術文章のIntegration Tests · Issue #63 · azu/azu
azu/azu#63
[Markdown] 電子書籍開発環境 · Issue #42 · azu/azu
azu/azu#42

[azu]

書籍は動的型付け or 静的型付けなのかという話

[azu]

テストはリファグリングを安心して行うためのものという側面がある。
文書でのリファクタリングというと文の並び替えがそれにあたりそう

[azu]

アイデア 💡 それぞれの章の小さなまとめ = まえがき を書くモチベーションを提供できるテスト方法があるとよさそう。

まえがきって書くモチベーションが持ちにくいし(読み手にとっても便利だと思うけど)、文章の順番とサマリを持ってる意味構造がテストに使えそう。

例えば、文章の順番を入れ替えた時にそれをチェックする仕組みとか

https://twitter.com/azu_re/status/653527439939780608

[azu]

文章を入れ方時に起きる問題。

• 初めて出てくる単語がいきなり説明無しで使われる
• まるで知っていることが前提の話が行われる

これを保証するのは順番を正確に持つSUMMARY.mdな気がする

[azu]

まえがき(ORGANIZATION.md)がカバーするのは、各章が何をカバーしているという話を書くべきだと思う。
なので、これで保証できるのは、本当のまえがきで書いてある事が、その章で解説されているかということ。

少量の文章からキーワード出すのに逆に辞書にないワードをキーワードするという手法がいけそう

• https://twitter.com/azu_re/status/653604897661648896

考え方的にはtf-idf - Wikipediaが近そう

[azu]

過去の関連発表

• http://azu.github.io/slide/niku_sushi/ebook_development.html
• http://efcl.info/2015/09/27/niku_sushi/
• https://azu.github.io/slide/individual/

[azu]

textlintの仕組みは http://azu.github.io/slide/reactsushi/textlint.html がよくまとまってた

[azu]

💡 このスライド自体をGitBookで書こう！
そうしたもっとメタの話がし易い

[azu]

https://github.com/azu/nodefest-technical-writing ベースを作成

[azu]

文章もコードと同じでばっと書くと一文が長くて、読みにくくなる。

コードの場合はこれを関数に分解したりしてリファクタリングするけど、文章の場合はセンテンスを分ける事で読みやすくする。

、の数を見たり、センテンスの長さを見たり、パラグラフの長さを見たりしてリファクタリングする。

[azu]

技術書の開発のモチベーションって自分のためというのが設定しにくいのが問題なのかな。
ブログのモチベーションは自分のためにというのが設定しやすい気がする。

[azu]

s/技術文書/技術文書/ に統一しよう

[azu]

技術書の場合一日で書き終わらないので、日によって敬体(ですます調)あるいは常体(である調)がまざることがある

[azu]

自然言語をテストしようとした時に、こんだけ自然言語使ってるのにテストが書けないのが問題

[azu]

Lintのモチベーション 朝Lint活動で細かな技術的負債を返済する - クックパッド開発者ブログ

[azu]

テストを書こうと思った時に、まずプログラミング言語と違ってテストを書くためのRunnerであったりフレームワークがない。
それを解決したくてtextlintを書いた(Lintする基盤的な感じ)

[azu]

ブログサイズ以上の文書を書くときに、文書の構造とかを気にしないと破綻する可能性があるので、それをどうやって設計していくか。
コードに比べて、文書においてはそういうツールが不足しているというか、使いやすいものがない。
(Wordとか一太郎がそれなのだけど、形式がプレーンではないという)

文章のモジュール化

読者から見た文章 = 実行結果
は元ファイルがモジュール化されてようがされて無くても同じだけど、文章を書く時やツールで解析する時はモジュールされてるほうが管理しやすい。

例として

find ja -type f -name '*.md' -exec cat {} \; > output.md
textstat output.md

日本文の読みやすさ : 58.9

となるが、個別ならもう少し見やすい

/Users/azu/.ghq/github.com/azu/JavaScript-Plugin-Architecture/ja/ESLint/README.md
number of characters : 8681
number of ListItem : 22
number of sentences : 193
Info: 平均が50、標準偏差が10とした読みやすさの偏差値
日本文の読みやすさ : 61.8

----------------------------------
/Users/azu/.ghq/github.com/azu/JavaScript-Plugin-Architecture/ja/connect/README.md
number of characters : 5962
number of ListItem : 18
number of sentences : 271
Info: 平均が50、標準偏差が10とした読みやすさの偏差値
日本文の読みやすさ : 57.7

----------------------------------
/Users/azu/.ghq/github.com/azu/JavaScript-Plugin-Architecture/ja/gulp/README.md
number of characters : 9477
number of ListItem : 37
number of sentences : 253
Info: 平均が50、標準偏差が10とした読みやすさの偏差値
日本文の読みやすさ : 57.5

----------------------------------
/Users/azu/.ghq/github.com/azu/JavaScript-Plugin-Architecture/ja/introduction/README.md
number of characters : 554
number of ListItem : 0
number of sentences : 11
Info: 平均が50、標準偏差が10とした読みやすさの偏差値
日本文の読みやすさ : 55.8

----------------------------------
/Users/azu/.ghq/github.com/azu/JavaScript-Plugin-Architecture/ja/jQuery/README.md
number of characters : 3351
number of ListItem : 7
number of sentences : 101
Info: 平均が50、標準偏差が10とした読みやすさの偏差値
日本文の読みやすさ : 56.5

[azu]

textint 派生ツールとして https://github.com/azu/textstat を作った

[azu]

誤字脱字はエラー表示がされないランタイムエラー
である

[azu]

サンプルコードを分けるのはメンテナンス性を上げるため。
モジュール化

文章もモジュール化した方がいい

[azu]

done https://azu.gitbooks.io/nodefest-technical-writing/content/