この記事は、Qiita株式会社のカレンダー | Advent Calendar 2023 - Qiitaの1日目の記事です。
Qiitaには、どんな機能やバグ修正がリリースされたかを確認できるリリースノートがあります。
リリースノートの更新は、機能やバグ修正をリリースする人が一緒に対応をする運用になっているのですが、開発するメンバーが増えてきたことにより、様々な記述スタイルで書かれている状態となっていました。
そこで、textlintを導入して記述スタイルを揃えるようにしたので紹介します。
textlintとは
日本語などの文章校正をするためのlinterです。
様々なRuleが用意されており、「ですます調」「である調」を統一するものや二重否定を使わないようにするものなどがあります。
また、Pluginを使うことでテキストファイルやMarkdownファイル以外のファイルもlintできるようになります。
RuleやPluginのリストは以下のWikiにあります。
また、現在(2023/12/1時点)Qiitaでベータ版として公開中の「文章修正提案機能」はtextlintをブラウザ上で動作させることにより実現しています。
「文章修正提案機能」については以下のリリースノートをご確認ください。
リリースノートが様々な記述スタイルで書かれていた
QiitaのリリースノートはMarkdownファイルとして管理しています。
例えば、ダークモードを正式版としてリリースしました - Qiitaのリリースノートは以下のようなMarkdownファイルになっています。
## ダークモードを正式版としてリリースしました
ベータ版として公開していたダークモードを正式版としてリリースしました。
**ログインユーザー向けの機能になりますので、利用する場合はQiitaにログインをお願いします。**
設定方法は[ヘルプページ](https://help.qiita.com/ja/articles/qiita-theme)をご覧ください。
| ユーザーメニュー | テーマカラー設定 |
| :---: | :---: |
|  |  |
| ライトテーマ | システムのテーマ(OSの設定がダークテーマの場合) |
| :---: | :---: |
|  |  |
冒頭でもお話しましたが、リリースノートの更新は機能やバグ修正をリリースする人
が一緒に対応をする運用になっており、人によって様々な記述スタイルがあり乱立している状態となっていました。
具体的には、以下のような記述スタイルがありました。
- 文末に「。」をつける/つけない
- リストの文末に「。」をつける/つけない
- 見出しの文末に「。」をつける/つけない
- 変更前後のスクリーンショットを載せるテーブルのヘッダが「変更前・変更後」か「Before・After」か
- テーブルのアラインメントが中央寄せか左寄せか
textlintを導入し、記述スタイルを整える
textlintを導入し、CIでチェックを走らせるようにすることで、リリースノートが統一された記述スタイルになりました。
また、社内で決めた記述スタイルにあったtextlintのRuleがなかったため、
- 見出しの文末に「。」をつける/つけない
- テーブルのアラインメントが左寄せ/右寄せ/中央寄せ
のtextlint ruleを作成しました。
textlintのドキュメントが非常にわかりやすく、またリポジトリテンプレートまで用意されているため、簡単に始められました。
- ルールの作り方について
- リポジトリテンプレート
実際に導入してみて
導入してからまだ間もないため、まだ話せることは少ないですが、レビュアー依存になってしまいがちな部分を機械的にチェックできるようになったため、属人性の排除や人的ミスが防げるようになりました。
また、リリースノートはユーザーの方に見せるものなので、見え方として統一された良い状態になったのではと思います。
最後に
Qiitaのリリースノートをtextlintでチェックし、記述スタイルを統一するようにした話でした。
リリースノート以外にも普段の業務を改善してくれそうな可能性を秘めていると思うので、より改善できないか検討していきます。
記事を読んでいただきありがとうございます!
ぜひ、Qiita株式会社のカレンダー | Advent Calendar 2023 - Qiitaを購読設定して、明日の記事もご覧いただけると嬉しいです。