このドキュメントは何？
このドキュメントは、社内のメンバーに向けて書かれた Hakky Handbook のイントロです。Handbook にコミットしたい or コミットするタスクが出てきた場合には、このドキュメントを読んでから書いてください。
目的
Hakky Handbook は、Hakky の会社・事業・カルチャー・技術に関する情報を体系化し、外部・内部に発信することを目的として情報の蓄積や発信を行なっています。Hakky について知りたい外部の関係者の方や、技術的なナレッジを知りたい方、社内のメンバーにとっても有益な情報を公開していくことを目的としています。
そのため、社内向けのドキュメントだとしても、公開する情報については書き方や品質、著作権などの問題を考慮して作成してください。
コンテンツ
コンテンツは以下のカテゴリーに分かれています。 Docs となっているところが、各事業についてや会社で扱う技術や情報などを体系的に取りまとめたものになります。それぞれの事業部でタスクなどを行う過程で、キャッチアップや行った内容などをまとめたりする際に、それぞれの事業部ごとに該当の箇所に記載をお願いします。
- Docs
- データ活用支援
- 機械学習プロダクト開発
- データ基盤構築
- Company
- Blog
また、 Blog については、まだ準備中ですので、まだコンテンツはありませんが、社内の情報などを不定期に発信していく場所としたいと思っています。
ドキュメントの編集方法
利用しているツール
Docusaurusという、Facebook が開発している OSS のドキュメント生成ツールです。このドキュメント生成ツールを利用して、管理しています。
Docusaurus の使い方
基本的には、公式のドキュメントを参照してください。
ドキュメントの編集環境の構築
Docusaurus を起動するには、node の環境が必要です。Hakky では nvm などを使うことを推奨していますが、バージョンが同じであれば問題ありません。リポジトリの直下にある .nvmrc ファイルの中にあるバージョンと同じバージョンの node をインストールしてください。
nvm を使っている人は、 .nvmrc があるので、
で指定のバージョンが使えるようになります。使っていない人は、 .nvmrc と同じバージョンをインストールしてください。
Ubuntu18.04にNode.jsをインストール
apt パッケージマネージャを使って最新版の node をインストールしようとすると、v10.19.0 になってしまいます。これは Ubuntu App Store にある最新版ですが、node の最新版ではありません。
そこで、以下の手順で.nvmrc ファイルの中にあるバージョンの node をインストールします。
# npmのインストールのために必要なライブラリをインストール
sudo apt-get install nodejs-dev node-gyp libssl1.0-dev
# nodeとnpmインストール
sudo apt install nodejs npm
# ｎをインストール
sudo npm install -g n
# 最新のLTS版を指定
sudo n lts
# 最新版を指定
sudo n latest
# 提供されているバージョンの確認
n ls-remote
# aptで入れたnodejsとnpmをアンインストール
sudo apt purge nodejs npm
sudo apt autoremove
# 再ログイン
exec $SHELL -l
# `.nvmrc` ファイルの中にあるバージョンのnodeを指定して、確認(以下は17.1.0)
sudo n 17.1.0
node -v
node がインストールできたら、パッケージのインストールのために、handbook のルートディレクトリで、以下のコマンドを打ちます。
これでインストールがうまくいけば完了です。起動するためには、以下のコマンドでできます。
これでブラウザ上で編集した内容の確認ができるようになります。
編集方法
GitHub のhakky-handbookというリポジトリの main のブランチから feature/hogehoge のブランチを作成し、コミットしたのちに、プルリクエストを出してください。
デプロイとホスティングには、vercelを利用しています。vercel のアカウントを持っている人だけがデプロイを行うことができます。
しかし、vercel は利用者 1 人あたりの課金のため、全員にデプロイ権限を付与することは難しく、デプロイできるメンバーが Hakky では限定しています。
そのため、ローカル環境での確認ができたら、PR を出して、レビューとデプロイを依頼してください。
vercel のアカウントを持っている人がmain ブランチにマージすると、本番環境にデプロイされ反映されます。
ドキュメントを書く前に読みたいもの
ここからは Hakky Handbook で記事やブログなどを書く前に意識して欲しいことなどを書きます。
記事に初めてコミットする方は、ぜひこちらを読んでから書いてください。
技術文書やブログの書き方の全体感について
まずは、文書を書くための技術のところから。Google の Techinical Writing の資料はとても良いのでおすすめです。
良い記事を書くために、事前に読んでおくと良い記事が以下です。
Hakky Handbook では SEO をそこまで強く意識することはしないですが、より多くの人に読んでもらうことが一つの目的でもあります。SEO などの意識は最低限持っておければと思います。以下は SEO に関しての情報です。
また、Markdown の書き方に慣れていない方は、いますぐに慣れてください！
書籍としておすすめなのは以下の本です。
タイトルと見出しの付け方
社内向けのドキュメントなどだと、結構意識が薄れてしまいがちですが、タイトルは非常に重要です。以下の記事などがタイトルと見出しをつける際に意識したいものがまとまっているので、参考までに。
Hakky Handbook での記事作成時のルール
基本的には、「記事の書き方 - LambdaNote」がすごく良かったので、こちらに準拠したいと思います。そのほか、特に守って欲しいルールや、docusaurus を使っている関係での追加でのルールなどは以下の通りになります。
表記
- 会社のことを表現するときは、「Hakky」で統一します
- 「です。ます。」で統一し、「である。」などの表現は使わないこと
docusaurus 利用に関するルール
- 記事のメタタグは以下の項目を最低限入れること。以下は、この記事で設定されているメタタグです。記事の一番最初にこれを入れてください。
---
id: handbook-introduction
