歌舞伎座.tech#14「OSSドキュメンテーション勉強会」レポート

歌舞伎座.tech#14「OSSドキュメンテーション勉強会」 - connpass の発表資料と口頭で話されていたことのメモです。
知見に満ちていて、これからドキュメンテーション業務に携わる人も、貢献してみたい人にとっても、とても為になる発表でした :)

study-meeting #OSS

Node.jsのドキュメント整備について

hiroppy😶 (@about_hiroppy) | Twitter さん

資料

how to manage the document of Node.js

ドキュメントは大切

  • 使ってもらうためにはドキュメントが大切
  • OSS の初めての貢献として入りやすい

Node.js コミュニティでの状況・運用規約

  • 日本語でもイシューの登録ができる
    • それぞれの言語がわかるコミッターの属するチャンネルにメンションがいく
  • コミットメッセージに規約がある (先頭に “doc” と付けるなど)
    • 検索しやすい
  • ドキュメントの更新が多い
    • 変更の承認者
      • core team
      • ドキュメンテーションチーム
        • syntax 周りをメインで見てる
      • working team
        • 例えば、HTTP2 関連の話題だったら http2 の working group が見る
        • 分野によって細かく分かれてる
    • レビューのポイント
      • typo
      • platform 依存
      • 英語の表現
    • style guide
      • I, you, we などを使わない
        • 指定ワードはダメ
        • “developers” など、第三者的な書き方にする
        • 誰も不快にしない表現にする
          • 男性・女性とか
          • 特定の人をささない
  • どうやって書いてるか
    • yaml
      • どういう変更がいつあったか管理したいため
  • HTML にコンバートするとき
  • サポートツール (これから使いたいもの)

C++リファレンスサイトcpprefjpでのドキュメンテーション

Akira Takahashi (@cpp_akira) | Twitter さん

資料

cpprefjp documentation

大切にしてること

  • 概要文章とサンプルコードを重視
    • 多くのユーザが必要としてるもの
    • 詳細を読まないユーザもいる
  • 標準ライブラリのリファレンスがメイン
      • 言語機能の解説の要望が多かったので、それも始めた

環境

  • Githubリポジトリでmarkdown書いてる
  • マネタイズ
    • サーバ管理者が個人で負担
    • Wandbox
      • 企業、個人スポンサーを集める
  • 議論の場
    • github の issue
    • チャット、twitter は使わない
      • 議論の履歴が追いにくい
      • 正式な議論の場ではない
        • みんなの合意を得る場ではない
  • 権限の付与
    • 随時募集
    • PR 送ってもらって、マージまでしたら付与
  • サンプルコードの検査
    • C++ はあまり仕様を大きく変えないのでサンプルコードが動かなくなることは稀
    • 自動化できるようにする予定
      • 断片的なコード
      • プラットフォーム依存のもの (windowsの環境変数を使うものなど)
    • コントリビュータの人に気付いてもらう

単語の揺らぎに対処するための手法と実装

Takahiko Ito (@takahi_i) | Twitter さん RedPen

資料

日本語の表記ゆれ 解決方法の検討と実装 // Speaker Deck

前提

  • 複数人数で書くと表記揺れしがち
    • Excel, エクセル など
  • クリティカルではないが発見するのにコストがかかる
  • メンテナンス性を落とさず、シンプルに実装したい

方法

READMEに何を書く？

ナゲット・もみあげ (@pocketberserker) | Twitter さん

資料

方針

  • 個人しか使わない想定の場合
    • ライブラリの管理のため
  • 他の人にも使って欲しい場合

要件

README に書くこと

  • 使い方
  • 環境
  • 公開している場所
  • CI へのリンク
    • なかったら信用が下がるかも？
  • Change Logs のリンク
  • API リファレンスへのリンク
    • README が長いと嫌厭しがち。詳細はリンクしておく。
  • LICENSE (悩ましい)

ツール

ドキュメントを直し続ける話

shigemk2 (@shigemk2) | Twitter さん

資料

ドキュメントを直し続ける話 #kbkz_tech * 何をするか * typo * リンク切れ、リンク先の修正 * どう直すか * typo * IDE の機能

how not to write textbook

Ryou Ezoe (@EzoeRyou) | Twitter さん

資料

HOW NOT TO WRITE TEXTBOOK

問題

  • XHTML で書いてた
    • 1MB の XHTML を編集するのが厳しい
    • 1 MB を超えると github の web browser 上で編集できなくなった
      • fork して PR 作って…ってやらないといけない
        • コントリビュータが減る
      • 結論: 分割しよう
  • サンプルコードが動かない問題
  • 最新に規格を反映されていない

解決

  • markdown でファイル分割
  • サンプルコードを抽出してコンパイルできるか検査するツール作った
    • Q: 断片化している、そのコードだけではコンパイルできないコードはどうするか
      • include 必要なもの
        • 必要なものを全てincludeしてコンパイルしてる (コード毎に必要なものを指定すると面倒なので、全てのサンプルコードで必要なものをまとめて include してる)
      • コードの一部を載せているコード(定義部分を省略しているものなど)
        • コンパイラが通らない前提のコードであることをコードのメタ情報として入れ込んである

Continuous API documentation: Docstandのご紹介

Tomoaki Kobayakawa (@kobadora) | Twitter さん

資料

Discussion

このドキュメントは素晴らしい

  • PHP
  • elasticsearch