はじめに 本記事はBASE アドベントカレンダー 2023の5日目の記事です。 こんにちは！BASE株式会社でエンジニアをしている田中です。 Creative Time1 Groupに所属し、主にBASEのBackOffice領域の機能開発を担当しています。 BASEでは、社内でのドキュメント管理の課題解決に向けて、2023年2月頃からツールをKibelaからNotionに移行しようという検証が始まりました。 この記事では、どのようにしてKibelaの記事をNotionに移行したのかや、移行の際に困ったポイントを紹介していこうと思います。 Notion導入にあたっての詳しい経緯や課題などについては、12/6公開予定のbonさんによる「Notion導入について（後編）」にて紹介予定です。 Kibelaのエクスポート機能とNotionのインポート機能 Kibelaには記事のエクスポート機能があ

『エンジニアリングマネージャーのしごと』を読んだ際に、アーキテクチャ意思決定記録（Architecture Decision Record; ADR）という用語を初めて知りました。最近、チームメンバーが増えてデータ基盤の設計に関してADRに残さないかという話が出ており、ADRについて自分なりに理解するために調べてみました。 ADRとは Architecture Decision Record（ADR）は、ソフトウェアアーキテクチャにおいて重要な意思決定をドキュメントとして残したものです。ADRには、ソフトウェアアーキテクチャに関する意思決定の履歴や根拠、その結果を記録し、プロジェクトチーム全体に共有します。ポイントは決まったことだけを記録するのではなく、意思決定に至った議論や背景、制約条件なども含めて記録することです。 ADRの主な目的は次のとおりです。 アーキテクチャ上の意思決定を明確に

こんにちは。電通デジタルでEMをしている河内です。エンジニアにおける採用・評価、スクラムマスターなどを担当しています。今回はすこし実装プラクティスから離れた話題になりますがお付き合いくださいませ。 弊社もご多分に漏れず完全テレワークを実施しており、かれこれ4か月が経ちます。その中で見えてきた課題とエンジニアチームとしてどう対峙したか、そしてそこで得た気づきを綴っていきたいと思います。この内容は、過去に開催したオンラインイベントでお話した内容になります。 テレワーク環境で私たちのエンジニア部門で急務と感じた課題テレワークが開始された2月後半、プログラミングやシステム開発プロジェクトを生業とする私たちの部では「リモート？全然OK。支障無いっす。」とタカを括っておりました。しかし開始されて間もなく、やっぱり慣れていない事が判明・・・。テレワークを経験されている読者の多くの方が感じていることと同様

ドキュメント文化は健全な組織のスケールのために必要　組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし

1200人以上の全社員がリモートワーク。GitLabが公開する「リモートワークマニフェスト」は何を教えているか？ スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ その コメント GitLab Handbookで面白かったもの@コミュニケーション編 GitLabのリモート統括責任者が語る　日本企業が「まずやるべきこと」 を読んだ。主題はGitLab社の https://about.gitlab.com/handbook/ である。 2022.02追記 GitLabで学んだ最高の働き方 Developers Summit 2022-02-18 2022.01追記 リモートワークのいま学びたい、GitLab Handbook非同期コミュニケーションのススメ - Qiita Handbook要点 「GitLab社ではリモートワークの中でも生産性高く働

はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた

テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。サイボウズの2023年度 新入社員向け研修の資料です。 本資料をもとにした書籍も発売中です：https://amzn.asia/d/2hQNEk2 Twitter：http…

大手ITスタイルガイドがベースGoogleやMicrosoftなど大手IT企業の英語スタイルガイドの基準がベース。一般的な英語表記から外れません。