【ScrumFestNiigata2024】a11yを起点とした組織横断を完了するためにアジャイルチームにとって大切だったこと100選

01_ADR.md アーキテクチャ設計のドキュメンテーション コンテキスト アジャイルプロジェクトのアーキテクチャは、別々に記述され定義されなければなりません。すべての意思決定が一度にされるわけでもなく、プロジェクト開始時にすべての意思決定がされてるわけでもありません。 アジャイル手法では、ドキュメンテーションに反対はしませんが、価値のないドキュメンテーションはいけません。チーム自身の助けになるようなドキュメントは価値がありますが、ちゃんと最新化し続けなければなりません。膨大なドキュメントでは、最新化されなくなることでしょう。小さくまとまりのあるドキュメントは少なくとも更新される可能性はありますよね。 また膨大なドキュメントはだれも読みません。たいていの開発者はソースコードサイズの合計よりも(byte的な意味で)大きな仕様書が書かれたプロジェクトを少なくとも1回は経験したことがあるでしょう

全てのAPIをProtocol Buffersで管理する / Manage all APIs with Protocol Buffers

はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。 ＜ご注意＞ 本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。 個人的に心がけていること 当該文書の作成目的や位置付けを冒頭に記載する

本資料は、技術文書を書くためのテクニックについて書かれた文書です。 解説は、心・技・体の3つの点から行います。 心：技術文書を書くときの心構え 技：技術文章の書き方 体：技術文章のネタを育てる方法 書く前に「心」を整え、「技」でもって育てたネタ「体」を読み手に届ける、という流れです。解説もこの順に沿って行っていきます。Read less

概要 先日、Tech Night @ Shiodome # 4というイベントに参加して、LTをしてきました。 どんなイベントか 「DevOpsと自動化」をテーマに、事例・知見を共有する場でした。 もとはソフトバンク様の社内勉強会で「外部ゲストを呼ぶ → 公開イベントになった」とのことです。 社会にシェアする姿勢が素敵だと思いました。 他の参加者の発表 あたりまえのことをあたりまえにやる難しさ AWS ECS （EC2 Container Service）を用いた AWS へのDocker コンテナデプロイ 自動化におけるコード管理 送信メールサービスをユニットテストしてみた DevOps、本当のところ こちらのConnpassのページに資料が上がっています。 どんな話をしてきたか こちらが当日の発表資料になります。 ざっくり説明すると DevOps（全体最適化）の前に、業務標準化（ドキュメ

astahの事例を探していた時に、設計書とモデル、プロセスをつなぐ為のアイデアが書かれた資料を見つけたのでメモ。 以下はラフなメモ書き。 間違っていたら後で直す。 【参考】 モデルへの参照を含む多様な設計情報の継続的統合ドキュメント化に向けて 【1】以前、Redmine大阪で宿口さんの講演を聞いた時、機能安全規格を満たすプロセスをRedmineで実現する話があった。 その実装方法を聞くと、Wordの要件定義書ドキュメントの目次の各タイトルに、チケット番号のリンクが貼られていて、そのリンクからRedmineチケットとWordドキュメントの整合性を取るような仕組みを実装されている、とのことだった。 第16回Redmine大阪の感想　#RedmineOsaka: プログラマの思索 その時は、なぜそんなやり方が必要なのだろうか？と不思議に思った。 確かに、WordドキュメントにRedmineのチケ

ちょっと書きたくなったので書くんじゃーい！ この文章を読み終わった時、読者がそれなりわかめ品質な文章を出力できるようになり、どこかに寄稿した時に全面リテイクを食らったりしないようになることを目指します。 mhidaka が 0歩目を書いてくれました！ 背景 筆者は普通のエンジニアです。その辺の開発とかしてる会社に勤めています。技術系の原稿も書きます。 原稿書きでご飯食べてるわけではありません(晩ご飯が豪華になることは稀にあります)。 今まで有能なレビューワー(muなんとかさんとか)編集さんとか(某社の安藤さんとか)とかとかに鍛えていただきました。 この場を借りてお礼を述べておきたいと思います。ありがとうございます。 なお、この文章は2013年10月時点での筆者(わかめ)のやり方です。 将来的にはより良いやり方を見つけるでしょうし、これとは全く違う書き方で上手にやっている人もいると思います。

先日複数人でDB設計をしている時「erdあった方が分かりやすいから作ろう」って話になり作ろうとしたのですが簡単にerdをｼｭｯと生成するツールが見つからなかったので作りました。 yml2erd 既存ツールとしてMySQL Workbenchなどあるにはあるのですが、作るのが面倒くさい + 作り方覚えるのが面倒くさい + 手でﾎﾟﾁﾎﾟﾁするのしんどいみたいな感じだったので自作の道を選びました。 また、Haskell製のerdというツールもあるのですが使いこなせませんでした・・・ インストール まず、graphvizという描画ツールをインストールします。macなら

pmconf2019 Tably小城の発表資料。 プロダクトの骨太の方針を作るためのフレームワークの使い方についての資料です。 https://2019.pmconf.jp/sessions/2019/11/13/S2-018/ こちらも合わせてご確認ください。 はじめてのPRD Tably 及川卓也 (@takoratta) https://www.slideshare.net/takoratta/prd-192302662

はじめに こんにちは植木和樹＠上越妙高オフィスです。クラスメソッドではAWSを始め、弊社で取り扱っている製品・サービスに関するサポート業務を行っています。 サポートでは日々様々なお問い合わせを受け付けるわけですが、ご質問に対する回答内容は正しくても、言葉が足りないためにお客様が不満に感じてしまうことがあったりします。「正しいことを伝えたのに、どうして不満と感じたんだろう？なにが足りなかったんだろう？」と対応を振り返る際に、私はキーワード／パターン／フレームワークに当てはめてみて考えるようにしています。 今回はサポートメンバーがよりよいサービスが提供できるよう、自分のアンチョコから5つのキーワードをご紹介したいと思います。 1.安心してもらう 自分で書いた回答内容を見返してみましょう。文章の内容がお客様に安心を与えているでしょうか？ 最後に「安心です」がつくように意識しましょう。また「文章の

The Node ecosystem is powered by its modules. npm is the magic that makes it all go. In the course of a week, Node developers evaluate dozens of modules for inclusion in their projects. This is a great deal of power being churned out on a daily basis, ripe for the plucking, just as fast as one can write npm install. Like any ecosystem that is extremely accessible, the quality bar varies. npm does

業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)

どうも若松です。 最近、過去のメモを掘り返して見ることがあるんですが、書いた時期によって書式がバラバラで、自分で書いたのにやたら見にくいことが多いです。 ならば書式を統一しようじゃないか！ いっそのことMarkdownで書いちゃえば他に転用できていいんじゃね？！ などと思い立ち、改めてMarkdown記法を調べたのでまとめます。 Markdown記法早見表 いきなり早見表かよ！というツッコミは受け付けておりません。 なんで早見表が一番上なのかというと、書いた本人が記法を忘れて見に来たときに一覧がほしいからです。 (ぶっちゃけこれが欲しくてこの記事を書きました) 記法名 書式 機能

技術文書向けのtextlintルールプリセットを作りました。 textlint-ja/textlint-rule-preset-ja-technical-writing: 技術文書向けのtextlintルールプリセット 今、書いているjs-primerで使用しています。 元々, JavaScript-Plugin-Architecture: JavaScriptプラグインアーキテクチャの本で実験していたルールをまとめたプリセットになっています。 そのため、実際に適応した状態で書けることは確認した内容がベースです。一部オプションで設定をゆるくしたり、textlint-filter-rule-commentsなどで無視する必要がある部分もありますが、許容範囲な感じでした。 そもそもなんでこういうツールが必要なのかについては以下のスライドを参照してください。 Introduction | 技術文

社内向けの教育資料を、ど素人でもわかるようにと思いながら作っていて、じゃあ「わかりやすい」って何だろうって考えてた。今まで読んできたいろんなわかりやすかった本とそうでない本を思い浮かべながら、一般的にここを注意すればわかりやすさを確保できるだろうっていうポイントを一旦まとめておこうと思った。そうしてまとめてみると、本に限らず人に何かを伝えること一般に適用される話だなと思った。 読む側の負担を減らす わからない＝理解をはばむ障害物がある。この障害物を取り除く／回避する作業が「わかる」ために必要になる。その作業を、作者ではなく読者が負担するとき「わかりにくい」本になる。 日本社会だと情報の受け手の側がこの「わかる」ための作業を負うことでコミュニケーションを成立させる傾向にある。空気を読むというようなことだ。そのため発信者側が事前に手を尽くしてわかりやすく発信するというのが苦手で、相手が汲み取っ

2016-06-30開催のssmjpでの発表資料です。 詳細: https://www.opslab.jp/publish/20160630-ssmjp.html (運用設計ラボ合同会社 波田野裕一)

残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門：プロジェクト成功確率向上の近道とは？（3）（1/3 ページ） ITシステム開発の問題点の一つであるコミュニケーションの失敗。本連載では、これを防ぐ方法としてお勧めしたい3つのドキュメントを紹介していく。今回は、「技術視点」のドキュメントとして、2000年代以降注目されている「Design Doc」について解説します。 IT技術がビジネスに貢献していくためには、まずはシステム開発を成功させることが重要です。本連載「プロジェクト成功確率向上の近道とは？」では、システム開発を成功させるために、コミュニケーションが果たす役割の重要性と、ドキュメントによるコミュニケーションの重要性について解説してきました。 連載1回の「ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門」、第2回の「サンプル例に見る

私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント