sigo.tosite

はじめに エンジニアリングをする中で「時間を取って後でドキュメントを書こう」と思う瞬間がある。 これは自分もたまにやってしまうことで、特にゾーンに入っている場合だったり、ガッと実装してしまったほうが早い場合だったりに起きているように思う。 しかしながら当然、ドキュメントを書かないことによる弊害というのも存在することは明白で、短期的に見るとスピードが出るのは間違いないのだが、長期的（と言っても状況によっては1ヶ月、2ヶ月と全然遠くない未来だったりする）に見て様々な問題が発生する。 ドキュメントがないことに対する弊害 例えば新機能の開発について考えてみる。 ドキュメントを整備しないまま実装した場合、実装した瞬間から「動いているものが正しい」状態になってしまう。仮にリリース前に仕様変更があった場合、ドキュメントがないと動いているものから仕様を読み解き、修正する必要があるかもしれない。 例として契約プランと契約年数で割引率が変わるロジックに手を加える場合、マトリクス表を一個書いておけば仕様把握は一瞬ででき、「パターンBをB'に変えたいんです」といった話がスムーズに行えるだろう。 だがマトリクス表がない場合はどうだろうか？どういう条件で分岐しているかコードリーディングした上でまとめ、どこをどうするか検討する必要が出てくるかもしれない。 この場合のコストは実装時にドキュメントを書くよりも工数が発生するように思うのは僕だけだろうか。 例えば新メンバーが加入した場合について考えてみる。 ドキュメントがないままオンボーディングするとなると毎回アーキテクチャやデータベース、システム構成について図を使って説明する必要があるだろう。 既存の仕様についても同様で、コードリーディングするかテストコードから挙動を追う必要があるかもしれない。 この辺りのキャッチアップは非常に時間がかかるもので、サービスが成長すればするほど、ドキュメントがない場合の工数は指数関数的に増えていくと思っている。 あるいはドメイン知識が浅いままに既存機能の修正を行った場合、考慮漏れが検知できず思わぬエンバグにつながるおそれもある（それを回避するためにコードレビューがあるが、コードレビューも万能ではないので）。 例えば既存機能の修正について考えてみる。 言わずもがなだが、ここがドキュメントがない弊害が一番大きく出る

コミュニティから学ぶエンジニアリング from naoto teshima 先日、社の先輩より打診がありFGNのイベントで登壇することになった。 急なお誘いだったので少々びっくりしてしまったが、久々のオフライン登壇と聞いて楽しみな気持ちが強かった。 FGN とは福岡市のスタートアップ企業支援に特化した施設で、イベントスペースとしても開放されているのでエンジニアイベントではお世話になることが多い。 社のメンバーがキャリアチェンジしてFGNの事務局に転向したのもあり、一登壇者としてではあるがイベントを盛り上げることで応援したいと思った。 「 コミュニティから学ぶエンジニアリング 」ということで、初学者向けに自分がかつて辿ってきた道のりをベースに、コミュニティとの関わりを通じて自分のキャリアと向き合っていけるといいねという話をした。 登壇資料を作っていく中で当時と比較して成長したなあと実感し、当時の頑張りを思い出してあの頃の自分には負けてられないなと思うなどした。 と同時に昔同僚だった方々のイケてる登壇を聞いて、自分も頑張らねばと気持ちを新たにしたのだった。 その後は韓国料理の Lock Stock で打ち上げだった。 イベントや技術のことについて話しつつ雑多な話をする体験そのものが久々だったのもあり、最高の夜を過ごすことができた。 言うまでもなく料理は最高に美味しかった。 韓国料理をちゃんと食べたことがなかったので新しい扉を開くことができた。 そのような体験を通してやはり自分はオフラインで何かをやることが好きなのだなということを実感したので、今後も機会を見つけて積極的に参加していこうと思う。 と同時にコミュニティを運営する人間としてそういう場を提供していき、たくさんのコミュニティから受けてきた恩を返していきたいと思った。 追伸: Notionは最高です。

はじめに こんにちは。FIREしてキャンプ三昧の生活を送りたいと思っている @tosite と申します。 先日「 社内ツールを作成したと思ったらいつの間にかOSS活動になっていた話 」で話していたOSS「 tosite/notion-page-repeater 」が完成したので使い方の実例を交えつつ紹介していきます。なお、導入についてはGitHub Actionsを用いることを前提としています。 また、現在β版ですので使ってみて不具合などありましたらご連絡いただけると大変助かります。 具体的な導入手順は ドキュメント に残してありますが、手順としては大まかに次の通りになります。 Notion側の設定 リピートする設定を保持する Settingsページ を複製する Notion APIトークンを発行する 自動生成したいページのテンプレートページを作成する 自動生成したいページのプロパティにDatetimeカラムを作成する テンプレートページのページIDを1-1.で複製したSettingsページのカラムに記載する 1-1.で複製したSettingsページ・自動生成したい親ページにAPIからのアクセス許可設定を行う GitHub側の設定 GitHubシークレットに秘匿情報を記載する GitHub Actions用のymlファイルを記載する 設定手順 1-1.リピートする設定を保持する Settingsページ を複製する 「複製」をクリックします。 1-2.Notion APIトークンを発行する https://www.notion.so/my-integrationsにアクセスし、「New integration」をクリックします。 以下のように設定します。 Name - 自由 Associated workspace - 先程Settingsページをコピーしたワークスペース Capabilities - Read content / Update content / Insert content 以下のAPIトークンは後で使用するため控えておきましょう。 1-3.自動生成したいページのテンプレートページを作成する 特に迷うことはないかなと思いますが、ページのテンプレートを作ります。 1-4.自動生成したいページのプロパティにDatetimeカラムを作成する カラム名は必

弊社ではNotionというツールを使ってドキュメント化を推し進めているのだが、先日  GMOペパボが全社員300名で使うNotion活用術｜リモートワークでも情報共有をスムーズに！  という記事が公開された。 その中の取り組みの一つとして「Meeting Noteなどの定例議事録を自動的に生成する」というものがあり、実は過去に自分が社内ツールとして作成・導入したものだった。 将来的にOSS化して使い勝手をよくしようとは検討していたのだが、ありがたくも次のようなフィードバックをいただいた。 ペパボさん、Notionテンプレートと自動化プログラムのオープンソース化してくれたら神だな〜 https://t.co/DdLp6KDoRm — takejune (@takejune) November 11, 2021 完全にやっていく機運が高まってきたので、より汎用的に改修を行った上でリリースしていきたい。 ちなみに仕組みとしては以下の通り。