この記事はGoodpatch Advent Calendar 2017の19日目の記事です。 私の開発チームでは現在、数十人規模で開発を進めているのですが、エンジニアが増員される中でどのようなインプットがあると、スムーズにプロジェクトに入ってもらえるかを色々と考えてました。今回は新たにエンジニアが加わる際に考慮しておくと良さそうな事を書きたいと思います。 ちなみに私はフロントエンドエンジニアなので、フロントエンド＆Webアプリケーション開発に多少寄った内容になってしまう事をご了承ください。 サービス理解 まずは何と言ってもサービス・プロダクトの説明が必要です。 例えば、以下のような情報をもとに、対話形式で説明していくと理解してもらいやすいかと思います。 サービスのコンセプト、提供価値 サービスの歴史 ターゲットユーザー KGI・KPI 競合他社、競合サービス 開発ロードマップ 開発体制、組

はじめに ドキュメントの管理方法はプロジェクトを進めるうえで頭を悩ませる話題のひとつであり、プロジェクトの本筋ではないこともあってなあなあで運用して後悔しやすい部分になります。ドキュメントを探しづらくなったり、ドキュメントが全然更新されずに使えるドキュメントがほとんどない状況になったり、ドキュメントの存在自体が暗黙知になったり、とにかく諸々の問題がよく起きます。こうしたことからプロジェクトに与える影響は存外に大きく、きちんと運用を考える必要性は高いと言えます。しかしながら、大袈裟な運用体制を敷いたり複雑なルールを作ったりすると、今度はコストが掛かり過ぎたりドキュメントを書くこと自体が難しくなったりもするので、費用対効果を考えると匙加減が難しい話でもあります。 そこで、本記事では比較的導入しやすく機能もしやすいシンプルな管理方法を提案します。なお、シンプルさを優先した方法なので要点を理解した

2023.03.28 スキル プロダクト 誰にでも分かりやすく、信頼できるドキュメントの存在は、プロダクト開発を円滑に進める上で不可欠だ。 2023年3月11日に発売された書籍『エンジニアのためのドキュメントライティング』（日本能率協会マネジメントセンター）を翻訳し、自身もエンジニアとしてさまざまな開発ドキュメントに触れてきた岩瀬義昌さんは、「プロダクトが育つ開発組織には、優れたドキュメントとドキュメントを尊重する文化がある」と話す。 では、プロダクト開発を成功に導く「優れたドキュメント」とはどのようなものなのか。また、そんなドキュメントが存在する組織は、そうでない組織とどんな差が生まれるのか。岩瀬さんに話を聞いた。 書籍『エンジニアのためのドキュメントライティング』翻訳者 人気ポッドキャスト『#fukabori.fm』運営者 岩瀬義昌さん（@iwashi86） 東京大学大学院修士課程修了

と実行すると、「DocFXSample」ディレクトリが作成される。 C#のプロジェクトとソースファイルを用意 ここではプロジェクト名をDocFXSampleとしたので、 csprojのファイル名はDocFXSample.csprojとなる。 コメントもつけておく。 using System; namespace DocFXSample { /// <summary> /// 基底クラス。 /// </summary> public class BaseClass { /// <summary> /// 基底クラスのメンバ。 /// </summary> public int sum; /// <summary> /// 基底クラスの仮想メソッド。 /// sumを+1して返す。 /// </summary> /// <returns>sumの値</returns> public virtu

はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、

はじめに こんにちは！ご訪問いただき、ありがとうございます！ 僕は現在、エンジニアとしての就職を目指しながら、インボイス制度に対応した請求書を、Web上で作成・発行できるサービスの開発をしています。 その開発を進めていく中で、読んでもらえるREADMEを作成したいという想いから、世の中の開発者がどのようにREADMEを作成しているのかを、GitHubで調べて分析をしました。 本記事では、たくさんのREADMEを見て学んだ、読みたくなるREADMEを書くためのコツを、実際に僕が作成したREADMEを例にしてご紹介します。 実際に作成したREADME 前提 今回ご紹介する内容は、未経験でエンジニア就活をする際に、採用担当の方が読みたくなるようなREADMEを作成することを目的とした内容となります。 また、実際に作成したREADMEを例にコツのご紹介していますが、時間の兼ね合いで、学んだコツを反

手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce

はじめに 自分は渋谷のWeb系開発会社にて執行役員兼エンジニアをやっています。(新卒入社3年目) 直近では6~8名程のエンジニアがいるプロジェクトで、ディレクトリ設計やissue作成、コードレビュー、スケジュール管理、PMへのUI/UX及び機能提案などを行なっています。 その中で自分が「エンジニアチームにとって開発しやすい環境整備」を色々試し、実践してきたので整理していきます。 この記事の主な対象者 エンジニアチームの開発モチベーションを上げたい人 エンジニアにとって開発しやすい環境の作り方 おことわり 今回紹介するのは自分が実践してきた一例であり、必ずしも正解というわけではありません 「こうしなさい」ではなく「こうするとより良くなるかも」といったモチベで書いています 具体的な開発の設計を紹介するものではありません エンジニアが開発しやすい環境作り 5つのセクションに分けて紹介していきます

（翻訳） リリースノートとは、ソフトウェア製品やハードウェア製品と一緒に配布される文書のことで、製品がまだ開発やテストの状態（ベータリリースなど）のときに配布されることもある。 すでに顧客に使用されている製品の場合は、アップデートがリリースされたときにリリースノートが顧客に届けられる。また、リリースノートの別の略語として、Changelog or Release logs, Software changes, Revision history Updates あるいは README fileがある。 日本語では リリースノートは、ソフトウェア製品の個別のリリースバージョンに関する 機能強化、仕様変更、不具合修正などを、エンドユーザーや製品購入者に対して提示することを目的とする。 リリースノートは個別のリリース内容について簡潔に記載されるものであって、仕様書やマニュアルの役割を担うものではな

リリースノートとは、ソフトウェアのリリース時に機能や目的などを知らせるための資料であり、ソフトウェアがアップデートされる場合も機能強化や不具合修正に関する情報をリリースノートとして公開します。リリースノートの中には優れたものもあれば悪いものもあるとのことで、「よいリリースノートを書くための10のポイント」について、ソフトウェア開発者のサイモン・ウィルソン氏がまとめています。 Writing better release notes https://simonwillison.net/2022/Jan/31/release-notes/ ウィルソン氏は、「リリースノートはオープンソースプロセスの重要な部分です」と述べ、GitHubなどでオープンソースのプロジェクトをリリースする場合、リリースノートを適切に書くことが大切だと主張しています。最近、「よいリリースノートの書き方」について考えていた

リリースノートとは ソフトウェアやWebサービスの場合、不定期にアップデートが行われることが一般的です。その際、何が変わったのか、どういった改善があったのかを明記するのがリリースノートになります。基本的にはじめてリリースされる際には作成されず、更新時に変更ポイントをまとめた文書として作成されるのが一般的です。 リリースノートの目的 アプリストアやWebサービスの場合、過去バージョンの利用は基本的にできません。そのためリリースノートを通じて変更点を把握することで、それまでできなかった新機能を知ったり、不具合が改善されたポイントを知ることができます。リリースノートがあることで、過去にどういった変更や修正が行われてきたかを確認できます。 オープンソース・ソフトウェアの場合、リリースノートにはどのPR（Pull Request）を取り込んだかもリストアップされます。それによってどの修正が取り込まれ

モバイルチームに誘ってもらい、noteのiOSアプリ（以下アプリと表記）のリリースノート作成を担当しています。ver 3.6.0（現在は ver 5.10.2）から担当し、その数もかなり多くなってきたので、自分がどういう意図を込めて書いてきたのか、振り返ってみようと思います。 リリースノートを担当するようになったきっかけ2020年5月のことでした。CXOの深津さんがSlackのリリースノートがいいとシェアしていて、それにのっかる感じで「大きいカイゼンのときはやってみたい」と手を挙げてみました。 ただ、当時の自分は何がすごいのか言語化できなかったので、自分もSlackのリリースノートを写経したことをきっかけに「UXライティング」という分野を知り、書籍や記事で学んだことをnoteにまとめて公開しました。 そのタイミングで、改めてモバイルチームから声をかけてもらったのです。 [余談] : 通常、

Confitだけでも月あたり5〜6回のリリースをしている計算になりますが、各リリースには大小さまざまな変更がいくつも含まれています。これは何らかの形で記録を残していかないと、何がいつ更新されたのか(または更新される予定なのか)わからなくなることが容易に想像できると思います。 アトラスサービスのセールス、サポートは、顧客である学協会や大会運営組織に対して、必ず担当者が付いています。特定のリリースにおいて、各担当者が「何が変更されたのか(何が変更される予定なのか)」、「どのタイミングでどの範囲のユーザーに影響があるのか」そういった内容を正確に把握し、必要に応じて顧客へアナウンスする必要があります。また、顧客から要望のあった機能を実現できるようになったり、困っていた不具合が解消されたり、そういった更新があれば、いち早く顧客へ伝えることができます。これらは、アトラスサービスをより活用いただくために

はじめに いざ、ウォーターフォールバリバリ1な開発スタイルだったところに、アジャイルな考えを適用しようとすると、ネックになるのが「ドキュメント」だと思います。 「金融系・お客様ほぼほぼ固定・サーバ保守する人がほとんど」な環境でアジャイル適用し始めた時に、断捨離を断行しました。 ただ、その時は捨て去りすぎて、少し問題2が起こっちゃいました。 本記事は、その経験を経ての整理結果です。 注意事項 この記事は仮説です。この仮説での実証ができていません。当然、上手くいくことを保証するものではありません。（が、一度実務に適用した結果を受けたモノなので、参考にはなると思います） アジャイルってキーワード出してますが、ウォーターフォールバリバリなところにもきっと効果があると思うので読んでって。 断捨離アプローチ いろいろ考えたのですが、「断捨離」を基準に説明するのがキャッチーで伝わりやすい気がしたので、「