障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
資料作成のポイント（定例、課題解決用） | フューチャー技術ブログ
はじめにTIG真野です。説明資料のスライドを作成するときにチームメンバーによくフィードバックしたポイントをまとめました。 以下この記事の前提です。 Google Slideなどのスライド形式が前提です わざわざスライド化しなくてMarkdownに箇条書きで良い場面も多いと思います。先輩はマインドマップでディスカッションしていて憧れました。ただ、この記事ではスライド前提とさせてください 5,6名のメンバーと気合を入れて資料作成し、数ヶ月かけてドメインエキスパートとディスカッションしました経験のまとめです 作成した資料は議論のたたき台＋システム設計における要件定義のような位置づけで用いました 資料はフルリモート会議で用いたので、なるべくスライドだけで完結して伝わるような志向があります この記事の記載内容は資料作成の全てのユースケースで使えるわけじゃないです コンテキストを共有しているチームメン
コンテナーとは | Microsoft Azure
輸送業界では物理的なコンテナーを使用してさまざまな貨物を、たとえば船舶や列車での輸送用に分離していますが、これと同様にソフトウェア開発テクノロジでも、コンテナ化と呼ばれるアプローチがますます利用されるようになっています。 ソフトウェアの標準パッケージが「コンテナー」と呼ばれ、これによってアプリケーションのコードと、関連する構成ファイルおよびライブラリがまとめられ、そのアプリの実行に必要な依存関係もまとめられます。これで、開発者と IT 担当者がアプリケーションをシームレスに、さまざまな環境にデプロイできます。 アプリケーションをある環境から別の環境に移動したときに正しく実行できないという問題は、ソフトウェア開発そのものと同じぐらい古くからあるものです。このような問題は一般的に、構成や基になるライブラリの要件およびその他の依存関係における相違が原因で発生します。 この問題に対処するために、コ
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
モノや概念をわかりやすく伝えるテクニック
録画：https://www.youtube.com/watch?v=49CzhFGqvD8 概要： 何かの技術、商品、サービスや機能など、モノや概念を人に説明しなければならない場面は多くあります。 伝えなくてはならないことはいっぱいあるけれど、何からどんな順番で伝えたらいいのかわからず、時間だけが…
GitHub Actions 逆引きリファレンス
1.この記事の立ち位置#自分がいつも調べていること、忘れがちな Tips や小ネタを列挙していく。そのため、網羅性は重視しない。 というのも、なにか調べていていろいろ読み漁った挙げ句、1周回って行き着くところは GitHub Actions の公式ドキュメントであり、たとえば Workflow の書き方は以下のページをよく開いている。 Workflow syntax for GitHub Actions - GitHub Docs それでも、公式ドキュメントで参照したい箇所を引っ張るための用語を知るまでに苦労することが往々にあり、この記事が、公式ドキュメントで参照したい箇所を導くための助けとなればと思い、書いていく。 2.Step と Job と Workflowの違いアレコレ#2-1.Step と Job と Workflow の違いの一行まとめ#Step < Job < Workflo
Private GitHub Pagesで社内ドキュメントを公開しよう！ - メドピア開発者ブログ
集合知プラットフォーム事業部の榎本です。筋トレのお供のプロテインが切れそうなので、次に購入するプロテインのメーカーとフレーバーに悩んでます。 GitHub Pages でアクセス制限 今まで GitHub Pages というと静的サイトをインターネットへ全世界公開するしかできなかったのですが、2021年に Private GitHub Pages の機能がリリースされ、限定されたユーザーのみに制限してページを公開することが可能になりました。 GitHub Pages を使って社内のドキュメントやナレッジを特定のユーザーだけに公開したり、企業内だけで共有したりすることができます。…（中略）… 今回の変更で、PrivateとInternalリポジトリでは、Private Pagesを使うことで、そのリポジトリを見れる人だけがそこから生成されるPagesのサイトを見られるという設定を行えるように
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文： www.industrialempathy.com 関連書籍： Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安：11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
すべての社内文書はMarkdownで書けばいいと思うこれだけの理由 - Qiita
Markdownを社内に布教したい、というモチベーションからMarkdownを勧める理由をまとめたもの。 同じようなことを考える方へ、周囲への説得材料になると嬉しい。 1. Markdownを勧める理由 1-1. 圧倒的理由 全人類がマークダウンを学習すべき理由｜情報デザイン力を鍛えよう Markdownとは (日本語Markdownユーザー会) をMarkdownで引用する。 Markdown（マークダウン）は、**文章の書き方**です。 デジタル文書を活用する方法として考案されました。特徴は、 - 手軽に文章構造を明示できること - 簡単で、覚えやすいこと - 読み書きに特別なアプリを必要としないこと - それでいて、対応アプリを使えば快適に読み書きできること などです。 Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、 最初は [Darin
【汎用ソフトスキル】ドキュメンテーションの続け方
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
GitHub+VSCodeでのMarkdownドキュメンテーションのプロジェクトルールを考える
概要 Word や Excel でのドキュメント作成を回避し、なるべく生産性高く、かつ、OS 環境依存なく、すべて基本無料で構成できるツールで、Markdown ベースで設計書を作成することを考えてみます。 GitHub 上で閲覧できる形でドキュメントを作成することを前提に、VSCode（＋プラグイン）を用いて、テキスト文書、表（テーブル）、図（構成図など）、キャプチャ、などをスピーディに作成し、PullRequest ベースで運用していけるように、プラグインを構成および、レギュレーションを作成してみました。 GitHub の README.md や Wiki に書いて使えるかと思いますので、併せて markdown 形式および、vscode のプラグイン推奨設定ファイル形式でも載せておきます。 もし、もっとこのプラグインを使うと良い、などアイデアなどありましたら教えていただけると幸いです
プログラミングファースト開発の必要性 - ひがやすを技術ブログ
ここではフローチャートの是非を論じるつもりはない。クソだから。もっと一般化してしまえば、○○設計書みたいに「設計書」と名のつくものは全部クソだ。だって動かないんだもん。 動かない以上、それら設計書が正しいのか、漏れがないのかは保証のしようがない。机上検証なんていう工程もあるらしいけど、君たちの脳味噌は何MIPSなんだと問い詰めたい。もちろん、机上検証で見つかる凡ミスもあるだろうけど、そんなのはズボンもパンツも履かずに会社に向かうのと同じくらいのレベルの間違いだろう。 結局はコードを仕上げてから動かして初めて「だめだこりゃ」ということになる。 ○○設計書は、動かないから検証ができない。だから、だめだというのは、半分あっていて半分間違っていると思う。システム開発の大多数は、最初に○○設計書を作成する。顧客にレビューしてもらったり、自分たちでも内部レビューしたりするが、あれは、有効性が低い。 動
PMによる仕様書では補えない運用フェーズに強いドキュメント作り｜さとじゅん
メルペイでプロダクトマネージャをしてます、さとじゅんです。 メルペイでto B向けプロダクトの開発をしてます。なので、主にto B向けプロダクトについての話になります。 たまに思うこと突然ですがPMは新しい機能を作る時は仕様書を書くことが多いですよね。 PRD（プロダクト要求仕様書）とかですね。 「Why」とか「What」とか「How」とか書きますよね。 それでリリースして運用していくと思うのですが、運用中にいろんな課題をこなしていくうちにひとつの事に気づきます。 「もう少しビジネスとシステムとオペレーションがひとつのつながりで理解できる資料が欲しいな」と。 to C向けのプロダクトに比べ、to B向けのプロダクトにはセールスやオペレーションのチームなど1つのプロダクトに関わる人が多くなる特徴があると思います。 PLGという考え方もあると思いますが、だいたいのto B向けプロダクトがto
「Docs for Developers」を読んだ - 勘と経験と読経
最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum
docker-compose コマンド概要 — Docker-docs-ja 19.03 ドキュメント
docker-compose コマンド概要¶ このページは docker-compose コマンドの使い方に関する情報を提供します。この情報はコマンドライン上で docker-compose --help を使っても確認できます。 Docker で使う複数コンテナ・アプリケーションの定義と実行 使い方: docker-compose [-f=<引数>...] [オプション] [コマンド] [引数...] docker-compose -h|--help オプション: -f, --file FILE 別の compose ファイルを指定 (デフォルト: docker-compose.yml) -p, --project-name NAME 別のプロジェクト名を指定 (デフォルト: directory name) --verbose 詳細情報を表示 -v, --version バージョンを表示
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Relay
Getting Started
テクニカルライティングの基本
脱ExcelしたいMarkdownテンプレート目次 - Qiita
Docker + Swagger + Stoplight Prismを用いたAPI仕様書作成環境+APIモックサーバーの構築方法 メモ - Qiita
