ドキュメンテーション

皆さん、こんにちは！もしくはこんばんは！ 楽楽精算プロダクトマネージャーの@wekkyyyyです。 前回は「楽楽精算のPRD(製品要求仕様書) Agenda」というテーマで記事をかかせていただきました。 tech-blog.rakus.co.jp 今回は趣向を変えて、「資料を作るときに考えていること」 いわゆるドキュメンテーションスキルについて書いていこうと思います。 目次は以下となります。 対象読者 筆者がどんな人物か なぜこれを書いたのか 注意点 資料を作るときに考えていること 【まずやる】仕事と作業を分けて優先度をつける 【いざ開始】1つのアウトプットを3ステップで分けて作業する 【15…

こんにちは、トモニテ開発部の Android エンジニアです。 この記事は every Tech Blog Advent Calendar 2023 の 5 日目です。 最近、 Android エンジニアに新たなメンバが増えました。 こんなこともあろうかと作っておいた贈り物としてドキュメントがありますので、どんなものか紹介します。 どんなドキュメントなのか GitHub にあるプロダクトのリポジトリの Wiki に、 アプリの構成 開発の前に 開発時の Q&A File Templates をまとめたものです。 アプリがどんな作りなのか？ 開発するにあたり守るべきことはあるか？ xxx をやり…

最近あるサービスのスマートフォンアプリに新機能を追加している。 そのアプリではAndroidネイティブ、iOSネイティブ、WebView、React Nativeの4種類の画面から構成されている。APIはREST APIとGraphQL APIの2種類がある。一見するとどこでどの技術を使っているのかわからないので、仕様を決めるためのコミュニケーションで誤解を生んだり、何度も同じ確認をするコストがかかっている。 この問題をどうしたら解決できるのだろうか。 根本的には APIの統合や、React Native を採用をやめてシンプルな構成にするというような採用技術の見直しとリファクタリングが必要だ…

はじめに こんにちは、ホワイトプラスのコアシステム開発グループでエンジニアリングマネジャー（EM）をしているinouehiです。 私はエンジニアの仕事の中で重要な位置を占めるコミュニケーションに興味を持っています。今回はその中でも、ドキュメントによるコミュニケーション、特に文章に注目したいと思います。 よいドキュメントと悪いドキュメント ドキュメントとは、誰かの頭の中にある暗黙知を見える化して他者への共有を可能にする仕組みと私は捉えています。これにより、ナレッジの拡散をある程度自動化したり、業務の属人化を軽減する等の効果が期待できます。うまく作られたドキュメントからは、かける手間に対して大きな…

10月からコンサルタントに出戻りしたエンジニアです. 入社前に想定していた以上に毎日が楽しいです*1. それはさておき, つい先日に前職の同僚であるエンジニアリングマネージャーの@jazzsasoriさんとサシ飲みしたのですが, 「エンジニアリングマネージャーとかテックリードとかになると, 議事録（的なメモ）」を取る力無いと辛いよね, 案外言及されてないけど という話題になりました, 酔っ払ってあんまり覚えてないけど🍻*2 で, どれぐらいの方がこの話題に興味あるのかな?と気になり, 昨夜、久々に前職エンジニアリングマネージャー氏と飲んでて、何かの拍子に「エンジニアがビジネスな力をつける訓練の…

見出しを5W1Hにするとわかりやすいドキュメントがかけそう。読む人の知りたいことを言語化するとなぜ・なに・なんのためのような形になると思うで読む人にとっては負荷が低くなりそう。 見出しがWhat, How, Whyの例 https://simperium.com/overview/ あと、例を書くときに目立つようにDO / DON'T をつけるとわかりやすい。「何々をしてください」 「何々をしないでください」 と書かれるとちゃんと読まないと反対の意味に取ってしまう。 やる・やらないを目立つように書いて、さらに色や記号で使っていると一瞬でわかってありがたい。 わかりやすいDO / DON'Tの例…

エンジニアの辛い仕事を消す本かも（多分） 2014年の秋にリクルートに転職してから何社か経て今も自社サービスのエンジニアとして働いてるマンです. リクルートに入ったとき, そしてその後の転職先*1などなどで, 社内外問わずのコミュニケーションの辛さ. 社内調整, 顧客折衝etc... コードじゃなくて, ドキュメントを書く仕事の辛さ. プレゼンテーション・説明そのもの. 技術わかんない上司に説明(ry*2 みたいな経験をたくさんしました&これはエンジニアをやってたら誰でも直面する事態かなと思います, 自社サービス企業だろうがSIer/受託開発の企業だろうが. そもそも, 昔の調査にもそんな雰囲…

新しいPCにセットアップする時に毎度詰まってるのでメモ！ Windows版 EpicGameLauncherを入れる https://store.epicgames.com/ja/download エンジンをインストールする EpicGameLauncherを一度終了しもう一度開く（.uprojectを関連付ける） VisualStudioをインストールする Optionとして必ず以下を含める（ビルドに必要） C++ プロファイリング ツール C++ AddressSanitizer Windows 10 SDK (10.0.18362 以降) Unreal Engine インストーラー バー…

2024/05/28(火)〜2024/05/29(水)のインプットからの厳選まとめ。 データ分析 データ分析全般 視野の広い観点を得られるコメント。 データアーキテクチャってこれのことだからね。データウェアハウスとか関係ない。営業スタッフの手帳に顧客データがあるなら、それも含めるから。https://t.co/Z4VMM2DXla pic.twitter.com/UDwaDeweTb— ゆずたそ / Sho Yokoyama (風音屋) (@yuzutas0) 2024年1月7日 www.ntt-tx.co.jp データエンジニアリング データの重要性とAIとの関連性は今後強まっていくだろうか…

※本記事は、ChatGPTによる意訳+翻訳を活用し、レイアウト調整したものです。 ※感想は、オリジナルです。 原文 意訳+要約 すべてのコードやライブラリ自体が技術的負債である / 高利率な技術と低利率な技術 詳細な考察 結論 ChatGPTへのQA Ｑ：どうやって可視化するのでしょうか？ Ｑ：利率の算出はどうすればいいでしょうか？ ステップ 具体例 感想＋雑記 原文 すべてのコードやライブラリ自体が技術的負債である / 高利率な技術と低利率な技術 - Lambdaカクテル 意訳+要約 すべてのコードやライブラリ自体が技術的負債である / 高利率な技術と低利率な技術 技術的負債の普遍性: すべ…

はじめに GLB事業部Lakehouse部の阿部です。 Databricks社が主催するDATA + AI SUMMIT（DAIS）が今年も開催されます！ Databricksは去年の秋ごろに、レイクハウスプラットフォームというシステムからData Intelligence Platformという新世代のシステムを発表しました。 今年のDAISのセッションもそのキーワードで検索すると11セッションもあり、この言葉を広めて行こうという思惑も伺えます。 https://www.databricks.com/dataaisummit/agenda?page=1&query=Data+Intellig…

技術的負債という言葉がある。もともとは、「楽するために導入したが、メンテにコストがかかるようになってしまった技術や構成」くらいの意味合いで使われているように思う。しかし、そもそも全部が負債ではないか、というのがこのメモの趣旨である。 負債 同僚とSlackで会話していると、「けっきょくどの言語を利用しても負債になるときはなるし、大抵負債になる」といった話になった。言われてみればそうで、基本的にコードというものは書いたそばから負債になっていく。去年書いたコードのことも思い出せない。 そんな中で思ったのだが、そもそも、負債になるコードと負債にならないコードとがあったり、技術が「負債化する」のではな…

はじめに セキュリティエンジニアの齋藤ことazaraです。今回は、オブジェクトストレージに対する書き込みに関連するセキュリティリスクの理解と対策についてお話しします。 本ブログは、2024年3月30日に開催された BSides Tokyo で登壇した際の発表について、まとめたものです。 また、ブログ資料化にあたりオブジェクトストレージを主題とした内容の再編と、登壇時に口頭で補足した内容の追記、必要に応じた補足を行なっています。 なぜ今、この問題を取り上げるのか？ 近年のクラウドリフト、クラウドシフトにより、クラウドを活用する場面が多くなってきていると思います。その中で、多くの場面で利用されるオ…

標記の大会が開催されます。 参加には申し込みが必要です。 詳しくは、アート・ドキュメンテーション学会のサイトをご参照ください。 http://www.jads.org/news/2024/20240615-16.html 日時：2024年6月15日（土）、16日（日） 第1日目：6月15日（土） 13:00-16:30 シンポジウム 16:40-17:30 第18回野上紘子記念アート・ドキュメンテーション学会賞・奨励賞授賞式 18:00- 懇親会（予定） 第2日目：6月16日（日） 10:00-12:00 総会（会員限定） 13:00-15:40 研究発表会 16:00-16:20 活動紹介 …

はじめまして、2024/4/1よりスマートバンクにサーバサイドエンジニアとして入社した長澤です！ 入社してから1ヶ月が経ったため、初心を忘れないよう入社の経緯とスマートバンクに入社してこの1ヶ月どうだったのかを赤裸々にお伝えし、実際どんな会社なの？という部分を知っていただきたいと思い記事を書きました。 簡単な自己紹介 大学でシステム情報学を専攻後、ものづくりがしたく新卒でSIerの企業に入社しました。その後、数社を経て前職のヘルステック企業から初めてRubyを書き始め、Ruby歴でいうとそろそろ2年になろうかなという頃です。そこでRubyの楽しさやコミュニティの良さに触れ現在に至ります。 入社…