ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
エンジニアのためのドキュメントライティング - ぱたへね
エンジニアのためのドキュメントライティング読みました。 最近の仕事の悩みに対して、方向性を示してくれた良い本でした。 www.amazon.co.jp 自分のチーム内にドキュメントの文化が無い人にお勧めします。 全体のざっくりした感想だと、この手の本にありがちな小言っぽいことは書いてなく、作って意味のあるドキュメントはどうあるべきかを書いてあります。仕事のドキュメントで悩んでいる人には、具体的な取り組みのアイデアがいっぱい見つかるでしょう。 背景 うちの会社は転職者が多く、開発への考え方がバラバラ。当然、ドキュメントに対する考え方もバラバラで必要なドキュメントがなかなか揃わない。今の仕事は各部署からの寄せ集めチームでもあり、ドキュメントのテンプレートみたいなものもない。 世代間の格差も結構ある。ベテラン勢はドキュメントは印刷され保管される前提であり、表示にバージョン、日付、部署、作成者など
ググり時間をぶった切る。AWSを最速で攻略するサイト13選 - Qiita
はじめに 自分がAWSをこれっぽっちも知らない頃、 ググって出てきたどこか知らんサイトからだと、「欲しい情報はこれじゃない」ってのが多くあった。 そんなこと繰り返していると エラー、トラブル時に即対応できない 間違って構築したせいで運用時に悪化してしまう 古いソースコードでエラーがでて動かない これで無駄な時間を過ごすことになる。 要は「ググって得たその情報で、作ったものは正しいのか？」 AWSは常にアップデートされ続ける 欲しい情報を手に入れるまで調べる時間を割くなら、 公式展開してるサイトから得たほうが正確である。 ということで、最速でAWSを攻略するサイトをまとめる。 この記事をブックマークでもしておくと、ググる手間も省けるだろう。 目次 AWSドキュメンテーション AWSサービス別資料 トレーニングライブラリ AWSブログ アーキテクチャーセンター ワークショップをする よくある質
FigmaとNotionでUML・経理処理・デザインまでAll in oneな仕様書を書いて、更新・共有を楽にしてる話 - Qiita
前提としての情報 単に「Figmaで要件定義のためのUMLも、外部設計のためのデザインも、内部設計のためのERDも全部つくるよ〜〜」という話をすると、ERD書くならデザインツールなんて使わないで、DBMSから自動生成できるツールとか使った方がいいじゃん、みたいな疑問が出るのは重々承知なので、そもそもこの形式に落ち着いた前提事項を書いておきたいと思います。 ご興味がなければ読み飛ばしてください。 筆者の仕事範囲 さて、冒頭で「事業会社でデザイナーとPMの狭間みたいな仕事をしてます」と書きました。キャリアの背景的には受託のPMっぽい仕事（厳密には違うんですが、本旨ではないので割愛します）→事業会社のインハウスデザイナー→現職という感じで、外渉から手を動かす所まで、必要ならなんでもします。 ざっくりいうと、機能の起案をして、経理などの関連部署に相談して、WBS引いて、UML書いて、画面遷移図書い
😡 「わかりづらい」ってどういう意味😡 - Qiita
はじめに ソフトウェアを開発するとそのマニュアルを書く必要があります で、このマニュアルのレビューでよくある指摘が「わかりづらい」 この指摘、(僕もよく言っちゃうけど)イラっとしますよね。「わかりづらい」って指摘がわかりづらい😡 この「わかりづらい」問題を回避するために、このページでは以下の点を考察します マニュアルが「わかりづらい」ってなんだよ どうやったら「わかりやすい」マニュアルになるのか 参考になるかもしれん資料 日本語の作文技術 内容はわかりやすい。単文をわかりやすく書くのに役立つ 理科系の作文技術 正直少ししか読んでない。先輩が「この本いい」って言ってた Technical Writing | Google Developers 主に単文を分かりやすく書くことフォーカス。 一部ドキュメントの構造に言及 Technical Writing Process Kingle Unli
僕が考えた最強の作業手順書 - Qiita
某所で見かけたシステム運用作業手順書の記事に、「作業直前に作業手順書の変更はしない」「手順書に無い作業をしない」といった事が書かれていました。 いや、それはあくまで心掛けの話であって、それも大事だけど、そもそも作業手順書はどうあるべきかという話が抜けおちているのではないか？それは世間ではあまり明文化されていないのではないか？と思いました。 不遜ながら、私が思う作業手順書のあり方を書いてみます。 1. 存在している まさか、本番作業を勘とノリでやっちゃうなんて。まさかね… 2. 保存されている Githubでも、Google Driveでも、Notionでも、Wikiでもいいですが、作業手順書は保管されていますね？えっ？保存していなかったら、同じような作業をもう１回することになったらどうなるんですか？障害が起きて、デプロイ手順に問題がないか調査したい時にどうするんですか？ なお、保存するなら
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
分かりやすい文章を書くために、私が意識していること
はじめに 私は、仕事でもプライベートでも分かりやすい文章を書くことを大事にしています。 文章が分かりにくいと、読む人がストレスを感じたり、質問や確認が増えて時間のロスに繋がったりすると思うからです。 『分かりやすい文章を書くために、私が意識していること』というタイトルでLTをしたところ、ありがたいことに好評でした😳 そこで今回、補足も兼ねて記事にしてみました。
AWS のアーキテクチャ図を描きたい ! でもどうすれば良いの ? - 変化を求めるデベロッパーを応援するウェブマガジン | AWS
こんにちは ! テクニカルトレーナーの杉本圭太です ! 最近読んで面白かった漫画は「海が走るエンドロール」です。 私は業務でお客様に AWS の様々なトレーニングを提供しているのですが、コースによっては AWS を利用したシステムのアーキテクチャ図を受講者自身に描いていただく演習を取り入れており、よくこんな相談を受けます。 「どうやって AWS のアーキテクチャ図を描くのが正解なんですか ?」 AWS のアーキテクチャ図を描く状況は以下のように様々な場面であり、同じような疑問や悩みをお持ちの方も多いのではないでしょうか ? 詳細設計で構成図が必要 チームで wiki などに図を貼り付けて残したい 構成検討フェーズなどで図を見てディスカッションしたい ワークショップを試しながら理解を深めるなど自分のために描きたい そこで今回は AWS アーキテクチャ図をどうやって描けば良いか悩んでいる方へ、
「良いFAQの書き方」を読んだので、その要点 - Qiita
読書感想文です。 感想 「FAQの書き方を学ぶ UX×テクニカルライティング勉強会 #5」を視聴したので、その記録 - Qiita にて読みたくなった本。 コールセンターの1回の問い合わせ対応コストは1回1200円らしい...月に10000問い合わせ来ていたら1200*10000円 ということ https://www.tactinc.jp/article/callceter-cpc FAQ整備に1月100万でも予算をかけてコール数を30パー減らせれば十分お釣りが来る ... ということでFAQの整備で効果を上げることの戦略が具体的に考えられる点でも読んで十分お釣りが来る本である。 要点 第1章：FAQはなぜ重要なのか 1.1 FAQの存在意義 お客さま向けFAQサイトとして カスタマーサポートにかかるコストの課題を解決する 顧客満足度と企業評価を上げる オペレーターのストレスを緩和する ユ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Documentation as Codeで継続的なドキュメント運用を実現する / July Tech Festa 2021 winter