はじめに こんにちは、食べログカンパニー 開発本部 飲食店プロダクト開発部の菅原です。所属する予約基盤チームでは、食べログ内の中心機能の1つである予約システムの開発・運用を担当しています。 大規模かつ長期にわたるサービス開発では、多くの開発者が共通の課題に直面します。その1つが「ドキュメントの陳腐化」です。 仕様変更にドキュメント修正が追いつかず、いつしかコードと乖離してしまいます。改善を試みますが、なかなか継続できずに挫折した経験を持つ方も少なくないでしょう。 ドキュメント管理には多くのコストを割けない現実もあります。そのため運用によるカバーへ頼らざるを得ない状況が生まれます。 この困難なドキュメント管理を、AIに任せることができれば大きなメリットが期待できます。 本記事では、主にソースコードと密接に関連する技術仕様書や設計書を「ドキュメント」と定義し、AI搭載のコードエディタであるCu

拙著『GitHub CI/CD実践ガイド』は内容だけでなく、読書体験にもこだわりました。AmazonやSNSでも読みやすいという声は多く、技術書としては珍しい観点で評価を得ています。 Amazonにおける「GitHub CI/CD実践ガイド」の読者レビュー 本記事では書籍の「読みやすさ」という切り口から、執筆の舞台裏を紹介します。 最高の読書体験を目指す 技術書の使命は、役立つ情報を届けることです。しかし筆者は役立つだけでなく、読んでいて心地よい書籍にしたいと考えました。そこでまず決めたのが「最高の読書体験を目指す」ことです。そして最高の読書体験を実現するため、次のような設計原則を定めて執筆しました。 シンプルにする：短い文章・簡潔なコード・直感的な図表へと磨き上げる ノイズを減らす：難しい表現は避け、読者を迷わせる要素は徹底的に取り除く テンポを重視する：読者の集中力を削がないよう、読ん

はじめに 今回はIPA（情報処理推進機構）が無料で公開しているエンジニア向け資料をまとめました。エンジニアやIT担当者におすすめの資料を厳選しています。 今回紹介する資料の結論 安全なWebサイトの作り方 要件定義ガイド DXスキル標準 情報セキュリティ白書2024 DX白書 情報セキュリティ10大脅威 2024 簡易説明資料 情報漏えい対策のしおり AI社会実装推進調査報告書 安全なWebサイトの作り方 安全なWebサイトの作り方では、Webアプリやサイトを作る上で知っておくべきセキュリティ知識を基礎から網羅的に学ぶことができます。 Webアプリケーションのセキュリティ実装 Webアプリケーションの安全性向上のための取り組み 失敗事例 各セキュリティ用語とそれに紐ずく詳しい解説や事例、解決策が網羅的に学べる資料になっています。 情報処理安全確保支援士を受ける人にもおすすめの資料です。 要

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? これは、同じエンジニアである妻から聞いた話なのですが、彼女の案件で「メンバー全員で公式ドキュメントを読みあわせる」という取り組みがあったそうです。 で、この方法「チーム全体にとって大きなメリットがあるんじゃないか？」と思ったので、共有させていただきます。 「誰も知らない」から「みんな知ってる」に 私は開発職なので、めずらしいことなのかそうではないのか判断がつかないのですが、その案件では、導入対象の製品について詳しい知識を持っているメンバーが一人もいなかったというのです。 誰もその製品をさわったことがなく、とりあえず強そうなメンバーを入れ

技術広報の941です。カケハシはPyCon JP 2024にスポンサーをし、ブースにて「カケハシ式、チャートでわかるふりかえりの技法」という冊子を作成し配布しました。普段はデータばかりを取り扱っているので、本というリアル媒体に関わることが少ないためなかなか苦労しました。 実際に配布した冊子 この記事では、イベントで配布するための冊子を印刷するためのデータ(組版といいます)を、Google Docsで作成する際に気をつけるべきポイントについて共有したいと思います。 この記事は秋の技術特集 2024の19記事目です。 組版とは Google Docsで作成するメリット Google Docsで作った組版データでハマりやすいポイント 入稿時に気をつけたいポイント 組版とは 文字や画像や表などの要素を配置して、読みやすく視覚的に効果的なデザインに仕上げる技術やプロセスのことを組版といいます。主に印

このブログは、テクニカルライター/ローカライズ リレーブログの1本目の記事です。 こんにちは！サイボウズでテクニカルライターをしている小林（@kbys_psb）です。 最近、テクニカルライターが社内にいる会社が増えてきたのを感じています。 ただ、一口に「テクニカルライター」といっても、会社によって、仕事の内容や働いている環境は様々です。 今回は、サイボウズのテクニカルライターがどんな組織の中で仕事しているのか、どんな仕事の面白さがあるか、どんな人が活躍しているのか、などを紹介します。 「サイボウズのテクニカルライター」が所属している組織 テクニカルライターやローカライズを担当するメンバーは、これまで製品開発を支援する「テクニカルコミュニケーション」という独立したチームにいました（一部を除く）。 2024年の組織体制の変更に伴い、このチームがなくなり、各メンバーはそれぞれ製品ごとの開発チーム

カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種

ぎーち(ブレイク兄) @BREAK_BROTHER 小型衛星の電源屋さんでヤンス。趣味でも衛星開発やっとります。衛星に携わってる方はぜひ仲良くしてクレメンス… 東方サークル(ネタタイトル萌えジャケットガチクラシック人工衛星サークル)"Windbreaker"のネタタイトル人工衛星担当です。 booth: https://t.co/tnUBatN1nz twpf.jp/BREAK_BROTHER リンク Yahoo!ニュース お願い「致します」漢字はNG? - Yahoo!ニュース 「よろしくお願いいたします」ビジネスメールでは常套句ともいえる一文に注目が集まっている。きっかけはX上のあるユーザーの投稿。そのユーザーは「よろしくお願いいたします」の「いたします」部分について、ひ 3 users

このブログエントリでは、テスト駆動開発（TDD: Test-Driven Development）の考案者Kent BeckがTDDの定義を改めて明確化した文章を、許可を得たうえで翻訳し、訳者の考察を沿えています。 きっかけ 2023年の年末、テスト駆動開発（TDD: Test-Driven Development）の考案者Kent Beckは、substackにTDDに関するポストを連投して論戦を繰り広げていました。TDDはその誕生から20年以上が経ち、その間に「意味の希薄化」が発生して議論が噛み合わなくなっていました。意味の希薄化（Semantic Diffusion）とは、新しく作り出された用語が広まる際に本来の意味や定義が弱まって伝わる現象です。 私（和田）はTDDと関わりの深いキャリアを歩んできました。Kent Beckの著書『テスト駆動開発』の翻訳者であることもあり、TDDの正

第0部　まずは「分かりづらい説明」を知ろう（p.14～） 第1部　口頭説明編（p.25～） 第2部　資料作成編（p.63～） 第3部　スライド作成編（p.81～） スライドのまとめ（p.115～）

はじめに はじめまして、8月にコネヒトに入社したy.ikenoueです。 突然ですがみなさん、生成AIは使っておりますでしょうか？ ChatGPTやStable Diffusionといった代表的な生成AIの発表から約1年が経過し、そろそろブームも落ち着くかと思っていたのですが、つい先日もOpenAI DevDayにてChatGPTに関する様々なアップデートが発表されるなど、相変わらず目まぐるしい日々が続いていますね。 弊社における生成AIの活用状況はというと、以前に下記の記事にて、Slack上でChatGPTと会話できる環境を社内提供しているという取り組みをご紹介しました。 tech.connehito.com 本日は、上記の社内ツールに新たに追加した「社内文書の参照機能」についてご紹介します。 「社内文書の参照機能」の概要と開発動機 まずは「社内文書の参照機能」の概要と開発にいたった動機

追記: 10/11 ハテブでバズっているようで、色々指摘があったので追記 getElement*は動作が早いのでIDやクラス名が自明の場合はgetElement*を使う方がいいと言う意見もあり、また、ページの表示で大量に呼び出されるわけではないからボトルネックにはならないと言う意見もある。 getElement*で返されるオブジェクトは動的な変化に対応しており、querySelector*は動的な変化に対応していないため、場合によってはgetElement*を使うといい。このサイトで遊んでみよう。 https://ja.javascript.info/searching-elements-dom#ref-263 for await ... ofは非推奨なので Promise.allを現代的な書き方にした 顧客先のブラウザが古い場合も考慮して、あえてレガシーな書き方もする場合があるらしい。現

はじめに 最近プロジェクトマネジメント関連の仕事をする機会が増え、(駆け出しですが)要件定義や設計関連の業務もするようになったので、私の経験を基に要件定義の具体的なプロセスや考え方について、まとめていきます。 この記事の対象者 要件定義の基本や思考プロセスを学びたい人 エンジニアからプロジェクトマネジメントをやりたい人 ビジネスサイドとエンジニアサイドのコミニュケーション能力を向上させたい人 具体的な事例を通して要件定義を学びたい人 前提 紹介する内容はあくまで一例であり、プロジェクトやチームの状況に応じて調整が必要 あくまで自分(駆け出しPM)の経験に基づいた内容を言語化しています プロジェクト規模は10名〜20名のWebアプリ開発を想定しています システム開発の全体像 一般的なシステム開発のプロジェクトは下記のフェーズで進んでいきます。 ※ コンサルの領域だと要件定義の前に企画構想とい

デジタル技術を活用して企業のビジネスを変革し、自社の競争力を高めていく「デジタル・トランスフォーメーション（DX）」が注目を集めるなか、従来のようなITベンダやシステム部門が中心になって要件定義をすすめるスタイルから、業務部門のユーザが主体的に関与するスタイルへの変革の必要性が増しています。 システムの要件を定義する責任は、構築されたシステムを利用してビジネスに貢献する役目を負うユーザにあると言われています。しかしながら、システム開発の遅延の過半は要件定義の失敗にあると言われるように、要件定義においては、その過程で様々な問題に直面します。 そこでIPAでは、要件定義の過程で直面する問題への対応をガイドすることが、ユーザへのよりいっそうの支援策となると考え、「ユーザのための要件定義ガイド(初版)」の内容を一新し、「ユーザのための要件定義ガイド 第2版 要件定義を成功に導く128の勘どころ」と

技術記事を書くまでのステップについて順にコツを解説していきます。 特に、技術記事を書きたくてもテーマ選定が難しい、文章が苦手だ、なぜか筆が進まない、うまくまとめられないといった方に読んで欲しい記事です。 一応、エンジニア歴としては数年以内のジュニアレベルの方を想定しています。 以下のように技術記事を企画して、書いて、公開するためのプロセスごとにちょっとしたコツをまとめています。気になるセクションだけでも読んでいただければ幸いです。 テーマを決めよう 対象読者を決めよう 章立てを決めよう 書こう タイトルを決めよう 【余談】技術記事を書く理由とは 筆者について QiitaとZennにて6年以上の記事発信経験があり、 Qiitaでは5,942Contributionsを記録、 Zennでは3,253Likesをいただいています。 テーマを決めよう コツ：テーマのカテゴリによって執筆のポイントや

架空の営業管理システムを作ってもらう前提で、ChatGPTに要件定義をお願いしてみました。 実験として軽く試すレベルで始めてみたのですが、予想を超えるクオリティでしたので、一部始終を皆様にもご紹介します。 ChatGPTとのやりとり まず、ざっくりと必要な機能の洗い出しをお願いしてみました。 あっという間に必要な機能を網羅的にリストアップしてくれまた。私自身、SFA/CRMをいくつか触った経験がありますが、適切な内容だと思います。 中には、「データのインポート・エクスポート機能」のように、検討初期段階ではつい忘れそうな機能も含まれています。さらに頼んでもいないのにオススメの検討プロセスまで教えてくれました。気が利いてます。 機能ベースだと要件の妥当性が判断しにくく思ったので、画面ベースで要件定義してもらことにしました。 「図で教えて」とできないことをお願いしたところ、やんわり断りつつ、意図

技術をわかりやすく伝えるためのテクニックとしての「テクニカルライティング」を学べます。Developers Summit 2023の登壇資料。開発者・エンジニアの方向け。 https://twitter.com/naoh_nak

研究発表のスライドの仕上げの目的は、単に見栄えを良くすることではなく、伝えたいことが正しく・詳しく・分かりやすく伝わるようにすることです。スライドの推敲の技術を知って、実践的に身につけましょう。大阪大学大学院の教員であり、2021年10月に『卒論・修論研究の攻略本（森北出版）』を上梓した著者が実例付きで解説します。 スライドの推敲とは？文章がそうであるように、スライドもまた、「伝えたかったこと」をいつでも正しく伝えてくれるとは限りません。そして、正しく伝わるはずだ、という淡い期待を裏切られたときは、本当につらいものです。 文章を推敲するように、スライドにも推敲をかけましょう。ただし、スライドを推敲する際に、単にスライド中の語句を推敲するだけでは不十分です。スライドは、文章とは異なる表現形式だからです。 とはいえ、実は、著者の別記事で紹介した文章の推敲技術は、スライドの推敲にも使うことができ

DK @game_sennin 初稿に取り掛かる前に、プロットや設定資料をつくる人は多いと思うけど、さらにその前の工程を設けてみませんか、という提案。 １００文字制限、２００文字制限は、本当に大事な情報を厳選した上で書こうとすると、意外に苦労するけど、その苦労が作品をより洗練させる、と考えていただければ。 pic.twitter.com/MgC29KmlEo 2023-01-10 14:14:17 DK @game_sennin 制限文字数内でなんとか書き収めることがポイントなので文字数は厳守してください。 「たくさん書くぶんにはいいだろ」と思わずに、どうしたら収まるか、残す情報と削る情報をどう判断するか、よく吟味して書くことに意味があります。 あまりないかもしれませんが無駄に文字数だけ埋めるのもNG 2023-01-10 14:14:18 DK @game_sennin この工程を避けよ