技術探し

JavaScriptを中心に記事を書いていきます :;(∩´﹏`∩);:

トップ > JavaScript > Node.jsのドキュメント管理について

Node.jsのドキュメント管理について

JavaScript Node

じいちゃんが米寿なため、実家で書いています。
あと家族増えてました👨‍👨‍👦‍👦
左の4ヶ月の子。

先日、こちらのOSSドキュメント勉強会で話しました。

kbkz.connpass.com

今回はスライドの要約です。

how to manage the document of Node.js

ドキュメントの重要性

f:id:about_hiroppy:20171120021722p:plain

opensource.guide

ドキュメントは大変重要で、ドキュメントが豊富かどうがでそのフレームワーク・ライブラリが使用されるかどうかも左右されると私は思います。

また、ドキュメントの貢献はOSSへの最初のワンステップとしてはちょうどよく貴重なコミットです。

例えばフレームワークであれば、APIの仕様以外にもexamplesを含めget-startedがあればユーザに優しいと思います。

Node.js Foundationについて

Node.jsはNode.js Foundationというところで管理されています。
Node.js github.com

ここでは、約600人の人々が約120チームに分かれて活動をしています。
また、チームとしては34ヶ国語のサポートがされています。
基本的にissueは英語以外でも問題ないという認識です。

Node.js

github.com

  • 19,914commits
  • 457 releases
  • 1790 contributors
  • 2,527 watchers
  • 42,472 stars
  • 8,831 forks

Node.の中には様々なドキュメントがあります。
以下は一例です。

  • BUILDING.md
  • CHANGELOG.md
  • CODE_OF_CONDUCT.md
  • COLLABORATOR_GUIDE.md
  • CONTRIBUTING.md
  • CPP_STYLE_GUIDE.md
  • GOVERNANCE.md
  • API Documentation

今回はAPIドキュメントについて話しました。

APIドキュメント

Docs | Node.js

nodejs.orgにあるのですが、APIドキュメントだけはNodeの.jsコアにあります。
なのでサイトの管理はnodejs/websiteチームですが、APIドキュメントはnodejs/collaboratorチームが行います。

コミット数

$ git log --grep doc: --pretty=oneline --check | wc
    3367   20994  237596

Node.jsではコミットのルールがあり、エコシステムが必ず先頭につきます。
ドキュメントの場合は、doc: です。

コミット数は3367でした。ちなみにテストは2853でおそらくエコシステムの中で一番多いコミット数だと思います。

issue/prのコメント数によるラベルの種類

f:id:about_hiroppy:20171121085509p:plain

One Week in the Life of Node.js

レビュワー

  • Collaborators
    • PRを承認する権利を持つので必須
  • Documentation
  • Website
    • 主にスタイル
  • その他モジュールに特化したWG(e.g. promise, stream, V8, etc...)

レビューをするポイント

  • typo
  • プラットフォームの依存
    • e.g. これはwindowsでは動かない等
  • コーナーケース
    • e.g. この場合は動かない等
  • 英語修正
    • もちろん、完璧な英語じゃなくても問題ないと思ってます

スタイルガイド

多いので言いたかったのだけ抜粋。

  • ファイル名はlowercase-with-dashes.mdで
    • jsのファイル名やモジュール名は-が多い(特に昔は)
  • I, we, you, his, guysなどは避ける
    • they, folks, people, developersなどを使う

github.com

Pronouns  |  Google Developer Documentation Style Guide  |  Google Developers

書き方

## module
<!-- YAML
added: v0.10.0
-->

> Stability: 3 - Stable

description and examples.

### module.property
<!-- YAML
added: v0.10.0
-->

* Type

description of the property.

### module.someFunction(x, y, [z=100])
<!-- YAML
added: v0.10.0
-->

* `x` {String} the description of the string
* `y` {Boolean} Should I stay or should I go?
* `z` {Number} How many zebras to bring.

A description of the function.

github.com

yamlの部分はバージョンの管理でそのモジュールが足されたとかの履歴を表示します。

markedとjs-yamlを使いHTMLに変換します。
lib/<module>.jsとdoc/api/<module>.mdが必ず1:1の対応になります。

オートメーション

CI

Node.js [Jenkins]

CIはNode.js Foundationから提供されているJenkinsを使います。
ここでは様々なプラットフォーム上でテストが行われます。
ドキュメントでは主にスモークテストとlintのテストが実行されます。

Lint

ESLintを使っています。

eslint.org

コアコードと同じルールを適応することにより、コードの書き方の統一化を行っています。

# Makefile

LINT_JS_TARGETS = benchmark doc lib test tools
LINT_JS_CMD = tools/eslint/bin/eslint.js --cache \
    --rulesdir=tools/eslint-rules --ext=.js,.mjs,.md \
    $(LINT_JS_TARGETS)

またdoc内にもeslintrc.ymlがあり、そこで適応できない部分がある場合は上書きしています。

ドキュメントをビルドする

HTMLへ変換します。

$ ./configure && make doc

./configureでNode.jsを生成して、それを使いdocを生成します。
そうすると以下のようなファイルが生成されます。

f:id:about_hiroppy:20171121091349p:plain

サポートツール

Node.jsではまだ使われてませんが、便利なツールを紹介しました。

APIの翻訳

ターゲットとの差分(行が増えた, 消えた等)が見やすく、複数人で翻訳がしやすいサービスです。 GoogleのプロダクトやVueなどで使われています。

gitlocalize.com

英語のタイポ検知

以前、PRでこれを使って修正したというのが来てこのツールを知りました。
修正もしてくれます。

github.com

まとめ

  • ドキュメントはめっちゃめっちゃ大切
  • 英語の主語には注意する
  • 自動化しよう

Code and Learn

来週のNode学園祭の2日目では、Code and Learnと呼ばれるNode.jsへコントリビュートする企画があります。
実際に世界中のNode.jsのコアメンバーの人たちがサポートをし、Node.jsへコミットします。大変おもしろい企画ですので是非参加してみてください:)

そのときに役に立てばいいなと思います。

nodefest.jp