技術文書をソフトウェア開発する話
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
技術文書をソフトウェア開発する話
まとめ3
技術文書の開発でもソフトウェア開発と同じ手法は取れる
GitBookとかRedPenとかtextlintなど文書を書くのに便利なツールが増えた
書くか書かないかは結局モチベーションの問題だと思います
ドキュメントは大事なのでちゃんと書いてね