ユーザーはドキュメントを「読みにくるけれど読んでいない」 “流し読み”しやすいドキュメント作成のポイント
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。さらに、ドキュメントの具体的な書き方と、フィードバックの収集について話します。前回はこちらから。 ドキュメントは「書き始める」ことが大事 岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？ 10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。 ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？ （スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き
文章の書き方を解説するための記事
はじめに 今回の記事では文章を書く方法を解説する。本記事ではエンジニアを対象としているものの、文章を書く能力はどの業界でも応用できる。単に「文章を書く」だけでは多義的な解釈ができるので、今回の記事では主に「論理的な文章を書く」能力に焦点を当てて解説する。 対象とする読者 エンジニアリングに携わっている人全員 これから技術記事を書こうと思っているエンジニア 「文章を書く能力」が必要不可欠な理由 エンジニアリングの現場では文章を書く能力が必要不可欠だ。その理由として、以下のようなことが考えられる。 ドキュメント化の重要さ：ソフトウェア開発のプロジェクトでは、設計から実装、テストに至るまでの各段階でドキュメントが必要となる。このドキュメントが明瞭に書かれていると、他のエンジニアやプロジェクトの関係者が情報を正確に把握しやすくなる。 コミュニケーション：チーム内でのコミュニケーションや、他の部門、
アジャイル的ドキュメンテーションのこころ - KAYAC Engineers' Blog
SREチームの橋本です。 アジャイル開発（ウォーターフォールとの対比の意味で）では「ドキュメントを書かない」、とまで言う人はなかなかいないと思いますが、「コードを読めばOK」といった声は実際の開発者からも聞こえることがあります。 ただ現場でドキュメントにより労力が削減できる場面は間違いなく存在し、またそのときには、軽いメモ程度のドキュメントでも間違いなく役に立つものではないでしょうか。 ややメンタル寄りの内容にはなりますが、ここではそうした観点からドキュメンテーションの「ミニマムスタート」を提案したいと思います。 何のためのドキュメント？ 要件定義書、基本設計書、詳細設計書……こうした「ドキュメント」を基盤として開発を行うウォーターフォールモデルの開発と比べれば、アジャイルではドキュメントが必須でない、というのは確かにそうでしょう。 しかし何の役にも立たないのか？ と言えばそれは間違いなく
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門
残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門：プロジェクト成功確率向上の近道とは？（3）（2/3 ページ） Design Docを書く いよいよ、Design Docを書いていきます。初めにやることは、システムに名前を付け、ドキュメントの冒頭の部分に署名し、そしてこのソフトウェアの目的やゴールを書くことです。 名前を付ける 不思議なことに、良い名前を付けると設計がはかどります。そのシステムにふさわしい名前を付けて、表紙に記載しましょう。 目的やゴールを書く 目的・ゴールの書き方の基本形は『このソフトウェアの目的は★★であり、◯◯を実現することがゴールである。』という定義文のスタイルです。何か誤解を生じる恐れがある場合は『なお、このソフトウェアには、××機能は含まない。』といった形で、除外されるものを明確にすることもあります。 目的・ゴールは、できるだけ明確に書い
Googleなどで利用されているDesign Doc入門 - MyEnigma
How Google Works (日本経済新聞出版) 目次 目次 はじめに Design Docの要点メモ 参考資料 MyEnigma Supporters はじめに GoogleなどのIT企業がソフトウェアを開発する際には Design Docというドキュメントを利用しているそうです。 Design Docは「設計書」と訳されることが多いですが、 日本語の設計書とは少し意味合いが違うようです。 今回は、このDesing Docの要点を、 末尾の参考資料を元に勉強してみたので、 自分用のメモとしてまとめておきたいと思います。 Design Docの要点メモ Design Docは、 これから新しく開発しようとするソフトウェアの全体の設計や、 既存のコードのpatchやプルリクエスト(PR)のコード変更の 基本的な要点をまとめる文書です。 PRを作成する前に、Design Docを作成して
AWSサービスのドキュメント履歴・リリースノート・フォーラムまとめ | DevelopersIO
AWSのサービスは、それこそ毎日の様に機能改善がなされ、弊社のAWSエンジニアが総出で取り掛かっても追い付かない程の早さで仕様変更・改善のお知らせが公式サイトのBlogやTwitter等で告知されています。 What's New from Amazon Web Services AWS Official Blog Amazon Web Services(@awscloud)さん | Twitter 各種サービス毎の更新内容については、それぞれの『ドキュメント』内に『ドキュメント履歴(Document History)』としてページが設けられています。(私もつい最近その存在を知りました) このドキュメントを追って行けば、最近どんな機能追加や更新が行われているか、情報のキャッチアップを行なう事が出来ます。しかしこれらのドキュメントは全て関連サービスのドキュメント内に個別に存在しているため、適宜
AWS クラウドサービス活用資料集 | AWS 公式
アマゾン ウェブ サービスの公式イベントのアーカイブおよびオンデマンドコンテンツの動画や資料がご利用いただけます。
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
運用ドキュメント2019/20190824-odc-operation-document
Amazon Web Services Documentation Overview
AWS Documentation