技術文書をソフトウェア開発する話
Introduction
1.
自己紹介
2.
目的
2.1.
なぜ技術文書というくくり？
2.2.
ブログ以上、技術書以下
3.
アジェンダ
4.
技術書
4.1.
JavaScript Promiseの本
4.2.
JavaScript Plugin Architecture
4.3.
JavaScript Plugin Architecture
4.4.
技術書に欲しい要素(Q)
4.5.
技術書に欲しい要素(A)
5.
GitBook
5.1.
What is GitBook
5.2.
gitbook.com
5.3.
GitBookはどんなところで使われてる？
5.4.
初めてのGitBook
5.5.
初めてのGitBookプレビュー
5.6.
GitBookの構造
5.7.
SUMMARY.md
5.8.
GitBookの表示確認
5.9.
gitbook.comとの連携
5.10.
Pull Requestでのレビュー
5.11.
gitbook.comとの連携機能
5.12.
GitBookまとめ
6.
技術書を書く環境はできたが…
7.
文書の継続的開発
8.
ソフトウェア開発での継続的開発
9.
文書をソフトウェア開発
10.
文章は動的型付け言語
10.1.
自然言語とプログラミング言語
10.2.
自然言語もLintしたい
10.3.
自然言語は変化する
10.4.
自然言語のLintは柔軟性が必須
11.
textlint
12.
DEMO
12.1.
ルールの紹介
12.2.
ですます調とである調の統一
12.3.
技術書は一朝一夕で作れない
12.4.
textlintのルール
12.5.
JTF日本語標準スタイルガイド
12.5.1.
JTF日本語標準スタイルガイド
13.
表記揺れ
13.1.
人間は表記揺れを吸収できる
13.1.1.
クローズテスト
13.2.
表記揺れは機械的にチェック
13.3.
プロジェクト固有の表記揺れ
13.4.
textlint-rule-prh
13.4.1.
prh.yml
13.5.
なぜプロジェクト固有？
13.6.
GitBook + textlint
13.7.
Atom + linter-textlint
14.
textlintの仕組み
14.1.
Markdown -> AST
14.2.
ASTとルールスクリプト
14.3.
textlintのルールの仕組み
14.4.
仕組みの仕組み
14.5.
木構造の走査
14.6.
エラーの通知
14.7.
仕組みの詳細
14.8.
texlint まとめ
15.
サンプルコード
15.1.
サンプルコードのテスト
15.2.
サンプルコードの種類
15.3.
外部ファイルとしてコードを書いて読み込む
15.4.
GitBookで外部ファイルの読み込み
15.5.
インラインコードのLint
15.6.
インラインコードのLint
15.7.
インラインコードのLint問題
15.8.
インラインコード専用のルール
15.9.
サンプルコードのテストまとめ
16.
CI
16.1.
文書を継続的開発する
16.2.
CIでテスト
17.
ここまでのまとめ
18.
3ステップで技術書を書き始める
18.1.
GitBook Starter Kit.
18.2.
Usage: GitBook Starter Kit
19.
継続的改善
19.1.
継続的改善
20.
Issue/Pull Request駆動
20.1.
Pull Request
20.2.
Lint結果をレビューコメントで通知
20.3.
Issue/Pull Request駆動
20.4.
Issueにメモを書く
20.5.
書き始めてない = 書いてない
21.
リファクタリング
21.1.
なぜテストするの？
21.2.
なぜリファクタリングするの？
22.
校正 ≠ 品質
22.1.
校正と推敲
22.2.
校正支援と推敲支援
22.3.
推敲するにはまず文書構造の把握
22.4.
textstat
22.5.
リファクタリングの現実！
23.
リファクタリング: 章の並び替え
23.1.
実験: 文章に対して文章でテスト
23.2.
キーワードテスト
23.3.
どうやってキーワードを取る？
23.4.
キーワードテストの効果
24.
まとめ1
25.
まとめ2
26.
まとめ3
27.
おわり: 参考
28.
Next Schedule
Powered by
GitBook
技術文書をソフトウェア開発する話
textlintの仕組み
Markdown/Text/HTMLをASTに変換
ASTは
TxtNode
というオブジェクトからなる木構造のオブジェクト
node.type
が"Header"という種類
node.raw
にテキストの中身、
node.loc
に行番号等の位置
これにより記号などに誤爆しないLintが可能になる