社内技術ドキュメンテーションを科学する - スタディサプリ Product Team Blog
最終更新日: 2024年05月07日(火) 1. ご挨拶 2. 本記事執筆のモチベーション 3. ワークショップを通じて得たフィードバック 3-1. Pains -過去抱えた/現在進行形で抱えている辛み- 3-2. Approaches/Solutions -Pains を解消するために取った方策や導き出した解決策- 3-2-1. えいやで場所を決め打ちしてしまう(e.g., GitHub Wiki + Google docs しか使わない) 3-2-2. 個人的に、2023/12/05時点で〜みたいな書き方を心がけている 3-3. Tips -効果的な手法- 4. オーディエンスからの反響 4-1. 気づきや学び・NEXT ACTIONS 4-2. プレゼンター(@hayat01sh1da)へのフィードバック 4-3. Slack での反応 5. おわりに 1. ご挨拶 初投稿となります
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。｜Fritz | Lead Product Manager @ Mercari
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が（たぶん） IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル（
GraphQLを徹底解説する記事
はじめに 今回の記事では、学習や実務でGraphQLを活用する人を対象に、GraphQLの全体像を把握するためのチュートリアル記事になる。本記事の対象読者は以下の通りである。 GraphQLの全体像を把握したい人 公式ドキュメントの理解で苦しんでいる人 GraphQLとは GraphQLはWeb APIを開発するためのクエリ言語である。REST APIの問題を解決するために、Facebook(Meta)によって開発された。Web APIの開発において、REST APIと比較して柔軟かつ効率的なアプローチを提供できる。さらに、GraphQLではクライアントが必要なデータの構造を定義することができ、サーバから定義したものと同じ構造のデータが返される。 詳細は後述するが、GraphQL最大の特徴は必要以上に大きなデータが返されることを防ぐことにある。これによって、GraphQLは必要最低限のリク
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
伸ばすのが難しい能力: 柴田 芳樹 (Yoshiki Shibata)
2018年6月1日に株式会社メルペイに入社して、4年が過ぎました。入社当時は、定年が60歳と聞いていたので、1年半の勤務だと思っていましたが、実際の定年は65歳であり定年まであと2年半です。 ソフトウェアエンジニアにとって重要な能力と（私は考えるが）、身に付けるのが難しいのが現実だと、この4年間で再認識したのは次の三つです。 開発の最初にAPI仕様をきちんと書けるソフトウェアエンジニアは少ない テストファースト開発を行っているソフトウェアエンジニアは少ないか、いない Tech Blogなどの執筆で、読み手を意識して、分かりやすい文章を書く、ソフトウェアエンジニアは少ない API仕様については、このブログでも何度か書いています（「API仕様を書く」）。テストファースト開発についても、「テストファースト開発」を書いています。分かりやすい文章については何も書いていないですが、「伝わる技術文書の書
ドキュメント駆動開発v2
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
ソフトウェアドキュメント作法 - maru source
こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました！ #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
Googleドキュメントがフィッシングサイトとして利用される｜ozuma5119 / Yusuke Osumi
この2,3週間ほど、私のメールボックスにほぼ毎日bitFlyerのフィッシングメールが届くようになりました。 私はサイバーセキュリティ分野での調査研究をしており、このような詐欺メールはさして珍しいことではありません。しかしこのフィッシングメールが誘導する先のフィッシングサイトは、あまり他に見ない特徴を持っています。そして今後の脅威となる可能性が高いと感じ、この文章を書きました。 フィッシングメール 届いたフィッシングメール自体は、よくあるタイプのものでした。不正なログインがあったからすぐ確認しなさい、と人を慌てさせてリンクをクリックさせる、一般的な手口です。 しかしこのリンク先が、2週間ほど前からGoogleドキュメントへのリンクとなったのです。 リンク先はGoogleドキュメント Googleドキュメントで作られたフィッシングサイトがこちらです。 見て分かるように、厳密にはこれはフィッシ
システム構成図をテキストで
Gigazineさんでdrawthe.netを取り上げていたので紹介です。使い方はGigazineさんのほうが丁寧なので、気になる方はチェックしてみてください。（2020年12月1日、追記） drawthe.netとは cidrblock/drawthe.netは複雑なネットワーク図も「テキストで書いてブラウザ上でSVGレンダリングできるようにしよう」というコンセプトのもと開発されたツールです。下図のように複雑な構成図も精度高く描くことができます。 拡大してみると情報量が多いこと、またいかに整っているかがわかると思います。 デモサイトも用意されているので、サクッと試したい場合はコチラが便利です。コードはGitHubで公開されています。更新が2017年末で止まってしまっているのが玉に瑕ですが、十分な性能を発揮してくれます。 drawthe.netを使いたい理由 美しい構成図といえばInter
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜安野貴博
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
社内情報共有についての考え方 - An Epicurean
タイトルのようなエントリを社内に向けて書いたので、手直しして社外に放流するものである。 社内で情報共有フローやガイドライン整備などを進めている。ルールは少ないに越したことはないので「ルール作り」にはしたくなくて、考え方やガイドラインみたいなところに留めて、文化や共通言語を醸成していきたいとも考えている。 これは、今後組織が大きくなる上で、「スピードを落とさないため」に必要だと考えている。新しく入ってきた人が立ち上がりを早くパフォーマンスを発揮してもらえるようにしたい。 オンボーディングの整備は大事で、それもやっていかないといけない。でも今のフェーズではどうしても未整備の部分も多い。そういう荒地を楽しんで走破できる自走力があって、自分で決めて整備もできて、組織と一緒に成長してくれる人を採用していきたい。なので「自走しやすい環境」を整えたい。そのために必要だと考えている点が以下の3点です。 デ
CTOを待ち受ける6つの経営課題
人工知能やビッグデータを活用したデジタルトランスフォーメーションが急速に企業活動における重要性を増している中、テクノロジーという重要な資産を担うCTO（Chief Technology Officer）は今後その重要度は増すことはあっても、減ることはないと思われます。CTOは、経営陣の一人として、提供するプロダクト・サービスにおけるサイエンス・エンジニアリング・ビジネスの3分野での広範囲な領域で、経営判断や実行に深く関わる事になります。昨今は、特にデータやAIといったコンピューティング重視の開発手法や世界規模での人材獲得の結果として、地理的な分散開発などの新しい経営要因の存在が無視できなくなり、CTOにとって従来にはなかった経営課題が生まれています。そこで、本稿ではCTOの6つの役割について、実践的視点から解説します。 なお、本文中の意見に関する部分については、筆者の私見であることをあらか
初めて書くPRD（プロダクト要求仕様書）
今回はIncrementsでQiitaのプロダクトマネージャーを担当されている及川さんにお話を伺います。早速ですがQiitaの概要やサービスコンセプトについて教えてください。 Qiita ... 当時の記事は2017年のものですので、今では立場も変わられており内容もアップデートされていると思いますが、何を記載すべきかを以下に列記します。 1. 概要 2. 背景 3. 製品原則 4. スコープ 5. 対象ユーザー 6. ユースケース 7. 市場分析 8. 競合分析 9. 機能要求 10. UX要求 11. システム要求 12. セキュリティ要件 13. プライバシー要件 14. パフォーマンス要件 15. リリーススケジュール・マイルストーン 16. マーケティング計画 プロダクト・マネージャーは海外ではmini-CEOとも言われるように、市場分析やマーケティング計画などといったプロダクトの
エンジニアのための、いますぐ使える文章校正テクニック - ICS MEDIA
ウェブ制作や開発の仕事で文章を扱う機会は多いはず。書き手は不自然に思っていない文章でも、読み手は違和感をもっていることがあります。文章校正テクニックを覚えるだけでおかしな表現は少なくなり、読みやすい文章を書けるようになります。 本記事では、ICS MEDIAで実践している文章校正の一例を紹介します。 レベル1、基本的な校正ルールを使う いろんな場面で使える基本的な文章校正テクニックから紹介します。 テクノロジー系の名詞は正しく記載しているか テクノロジー系の名詞を間違って使うと、「本当に技術に詳しいの？」と読者からの信頼度が下がります。名詞は大文字小文字、スペース有無含めて正確に記述しましょう。 Github → GitHub（Hは大文字） Javascript → JavaScript（Sは大文字） After Effect → After Effects（複数形の「s」を忘れてはいけな
Seminar | Deep Learning JP
参加条件： Deep Learning基礎講座修了か、もしくは同等レベルの知識を持つこと 基本的に毎週輪読会に参加できること 発表が割り当てられた場合，発表できること 参加方法： 下記のフォームをご記入下さい。（参加には基本紹介が必要となります。） https://docs.google.com/forms/d/e/1FAIpQLSfosRjTx_kFljDyVLjTKn_XLwCLWPOT6fOYUSwvINdUbuvfJw/viewform 輪読会の進め方： 2020年8月現在，会議は原則オンラインで行っています（コロナの影響）．オフラインイベントの復活時期は未定です． 大枠：45分,小枠20分×2の合計3件です。 時間は質疑込みの時間です。 基本は最初は小枠の発表に割り当てます。その中の一部メンバーに大枠の担当を依頼させていただきます。（大枠で話したいという方、何か話したいテーマがあ
Go な WebAPI のテスト＆ドキュメントの模索 - Qiita
みなさん Go な WebAPI のテスト＆ドキュメントどうしてますか。僕はまだ数ヶ月程度の Go 経験しかなく模索しながら、まだまだ彷徨っている状態です。そこで現時点での自分なりのやり方をまとめておこうと思います。こうやったほうが良いよ！というアドバイスがあればぜひお願いします サンプルコードはこちらのリポジトリに雑においてあります。 https://github.com/zaru/go-api-documents-demo ツール類 今記事では echo + sqlx な構成を例にしています。 使っているもの Go 1.9.x labstack/echo jmoiron/sqlx stretchr/testify/assert API Blueprint aglio dredd drakov テストライブラリは stretchr/testify/assert だけ使っています。モックな
ドキュメンテーションコストを下げる - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 開発者が開発を進めているときに大事なことは、できるだけ本業の開発に専念できる時間を増やすことだ。 本業の開発時間を確保するのに役立ってきたこと ソースコードの管理コストは、バージョン管理ソフトウェアで改善した。 タスクの管理コストは、課題管理システムRedmineなどで改善した。 これによって、発生しているトラブルの状況を何人もにそのつど説明しなおす手間が減った。Redmineにチケットを発行して、そのつど状況を書いてしまえば、細かい状況をきれいさっぱり忘れてしまえる。 ソースコードのドキュメンテーションをMS-Wordで作るのではなく
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
技術をわかりやすく伝えるためテクニカルライティング
SRE 研修
テクニカルライティングの基本
