テクニカルライティングの基本テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
AWS テクニカルサポートで得た暗黙知をまとめてみた | DevelopersIO
AWS テクニカルサポートを 5 年経験して アノテーションの荒川です。 クラスメソッドメンバーズをご契約いただいているお客様のテクニカルサポート業務を始めて、早 5 年が経過しました。 私が対応したチケット件数をざっくりと調べたところ、本日時点で 1685 件でした。 最近は私がチケット対応する機会は減りまして、チケット対応メンバーの教育（新入社員から各チームへ所属するまでの育成）やチケット相談に使う時間がメインです。 その中で、今まで何となくこうやって対応すると上手くいくと感じていた暗黙知をメモ書きしていたので、今回ブログとして公開します。 回答者側で意識したいこと 技術的なお問い合わせに関するガイドラインを参考にする AWS サポートのガイドラインは、一般的なカスタマーサポートでも使えます。 一文を短くし、適宜改行を挿入する 例: 一行にぎっしり × お客様環境をお調べしたところ、E
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する | DevelopersIO
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する できればドキュメント書きたくないなー。はやくAPI実装したい！俺の頭の中に全部仕様入ってるから！俺が仕様だ！ ... その仕様、API Blueprintでドキュメントにおこしませんか？ はじめに デバイスが多様化し、その違いを吸収する統一的なインターフェースが求められる昨今、Web APIはその回答のひとつといえます。弊社でも、モバイルアプリとWeb APIを組み合わせてサービスを構築することがあります。 Web APIが登場する開発では、モバイルアプリ（APIクライアント）メンバーと、APIサーバメンバーのコミュニケーションが不可欠です。開発を円滑に進めるために、APIの仕様書 が必要になります。お互いがAPIの仕様を想像して勝手に開発を進めたのでは、いざ結合したときに悲惨な結果になることが目に見えてい
Swaggerの概要をまとめてみた。 - Qiita
最近は API Blueprint で仕様書を書くことが多かったのですが、Swagger が世界標準になるかもしれない、ということもあり、開発の効率化を進めるためにも概要をまとめてみようと思った次第です。 Swaggerとは Swagger は RESTful APIを構築するためのオープンソースのフレームワークのことです。「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進していて、その標準フォーマットがSwaggerです。Swaggerには多くの便利なツールが提供されていることもあり、多くのメリットを享受できそうです。 Swagger Spec を書いておけば自動的にドキュメント生成までしてくれ、それだけではなく、ドキュメントから実際のリクエストを投げられる優れものです。 Swaggerのツール群 ツール
プログラマーから見たPDFファイル - アンテナハウス PDF資料室
更新日: 2020年8月14日 このページの目的 プログラマーは、クライアントから提供されたPDFファイルで、その要求を実現させようとしたとき、PDFのどんなところを見ているのでしょうか。このページでは、ちょっと珍しい視点でPDFファイルを解き明かしていきます。 自分でプログラムを書いてPDFファイルからテキストデータを取り出したいという人も、ぜひご一読ください。 はじめに PDFファイルをクリックすると、あたかも紙に印刷したかのように、どんなマシンでも同じような見た目で文章や画像がディスプレイに表示されます。 この単純な事実は、日常的にPDFファイルを利用していると当たり前に感じられるかもしれません。しかし、よくよく考えると驚くべきことです。 いったい、どのような仕組みがあれば、「過去から現在に至るさまざまな種類のコンピューターで見た目を変えずに同一の紙面を再現する」という目的を達成でき
知らないようでやっぱり知らない仕様書のレビュー技法 - Qiita
はじめに 皆さん、仕様書のレビューは実施していますか？テストで不具合を見つけて修正することも大事ですが、そもそも仕様書の段階で問題があるのであれば、レビューでその問題を検出して修正しておきたいですよね。 一口に「レビュー」といっても、様々なやり方が知られています。時と場合によって効果的なレビューの方法は変わるとは思いますが、まずは色々なレビューの方法を知っていることで、どんなやり方でレビューしたら良いか考えるきっかけになるはずです。ということで、この記事では、色々なレビュー技法（Reviewing techniques）について解説したいと思います。 この記事で扱う「レビュー」の範囲 仕様書（要求仕様書、要件定義書、機能仕様書など）のレビューを想定して記載します。コードレビューについては対象としていませんのでご注意ください。ただし、記載しているレビュー技法が、それ以外の文書やコードレビュー
文書執筆の指南書で解説されている問題点を RedPen で発見する
はじめに 本稿では技術文書の指南書で解説されている文書の問題点を RedPen で発見する方法について解説します。紹介する文書の問題点は以下の指南書で解説されている内容です（執筆者の敬称略）。 理科系の作文技術（木下 是雄） 数学文章作法（結城 浩） 文章の書き方（山本 和彦） 上記の指南書で解説されている問題点の多くはシンプルです。しかし残念ながら、指南書で解説されている文書の問題点はプログラムのコーディング規約ほど広く認知されていません。さらに問題点に注意しながら文書を執筆するのは簡単ではありません。たとえば、textlint を開発されている @azu_reさん は以下のように述べています。 あなたはIMEほど記憶能力が高くないが、IMEはあなたほど賢くない。 なので二つで作った文章には綻びが生じやすい。 それをtextlintやRedPenなどの第三者が見つける。 — azu (@
AsyncAPIでつくるMQTTインターフェイス仕様書！ | DevelopersIO
お疲れさまです。サーバーレス開発部の新井です。 今回は、MQTTのインターフェース仕様書を作成するツールAsyncAPIに関する記事です。 弊社岩田のブログでも促されたので頑張って書いていこうかと思います。 参考サイトURL オンラインエディタ ドキュメント生成 コード生成 背景 最近はAWS IoT案件に携わる機会が多く、デバイスの開発者とMQTTのトピックやパラメータの設計をやり取りする機会が増えています。 で、ここのインターフェイスを統一的に管理したいというのがあり、Swaggerみたいな規定フォーマットに沿って記入すればドキュメント作成してくれるようなツールを探したところ、AsyncAPIなるものがあったので、今回はこちらを紹介していきます。 ソースはYAMLで作成して、フォーマットに沿って入力していけば、最終的には上記の様にHTMLファイルベースのドキュメントを生成してくれます。
分厚い仕様書からは読み解けない、Bluetoothの単純な疑問
Bluetooth Classicの基本は「Core Spec 4.2」という仕様書にまとめられています。そこには複数のフレームタイプが規定されています。それを見ると、一体誰がどのように選択して使い分けるのか、という単純な疑問が生じるはずです。今回は、Bluetoothのフレームタイプの使い分けについて仕様書から読み解いていきます注1）。 いくつもあるACLのフレームタイプとデータ長 Bluetooth ClassicにはACL（Asynchronous Connection Less）という一般データ用フレームと、SCO（Synchronous Connection Oriented）という同期オーディオ用のフレームがあります。このうちACLにはDM（エラー訂正機能のFECあり）とDH（FECなし）の2種類があります。これに625μ秒の「スロット」をいくつ連続で占有するかというスロット数
「要求仕様問題」と次の課題
いわゆる「要求仕様の問題」が発生する1つの側面として、要求仕様の「曖昧さ」がある。開発の指針であるはずの要求仕様が曖昧なため、後続の工程に悪い影響を与え、指針としての役割を果たしていないというものだ。本稿では、要求仕様の曖昧さを回避する方法について述べる。 厳密な要求仕様が要求される背景 曖昧さを回避する方法を論じる前に、まず要求仕様を厳密にしなければならない背景を説明する。「曖昧ではない厳密な要求仕様書」の記述法といえば、真っ先に取り上げられるのが形式手法だ。しかし、精密な制御が求められるにもかかわらず、形式手法を用いなくてよい開発対象もある。例えば複写機やプリンターなどの機能を1台にまとめた「複合機」もその1つ。複写機は我が国の輸出を支える重要な製品だが、開発において厳密な形式手法で仕様を記述をしているという話を聞いたことがない。複写機は精密な制御を行う製品だが、多少の瑕疵は許されてい
サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック (1/3)：プロジェクト成功確率向上の近道とは？（2） - ＠IT
サンプル例に見る機能仕様書の基本的な書き方＆読みやすくする7つのテクニック：プロジェクト成功確率向上の近道とは？（2）（1/3 ページ） ITシステム開発の問題点の一つであるコミュニケーションの失敗。本連載では、これを防ぐ方法としてお勧めしたい3つのドキュメントを紹介していく。今回は、Joelの機能仕様書を日本人向けにカスタマイズされたものを例に、機能仕様書の基本的な書き方、読みやすくする7つのテクニック、仕様書作成ツールは何を使うべきか、誰が書くべきかなども解説します。 連載目次 連載の第1回の前回「ドキュメントは最強のコミュニケーションツールである――Joelの機能仕様書入門」では、ITシステム開発がビジネスに貢献していくためには、まずは開発の成功が出発点になること、そしてITシステム開発におけるコミュニケーションの重要性、そしてコミュニケーションにおけるドキュメントの重要性について説
使えないICTシステムを排除する要件定義手法「Tri-Shaping」
2月9日、富士通はシステム構築における要件定義のノウハウを集大成した「Tri-shaping」を発表した。コスト削減や期間の短縮、なにより品質向上が図られるという。 発表会の冒頭、富士通のSIビジネスと要件定義についてシステム生産技術本部 本部長の柴田徹氏が説明を行なった。柴田氏は経営視点で業務プロセスを変えられる人がいない、業務視点でICTシステムを変えられる人がいないというなか、激しい環境変化を乗り切らなければならない企業の現状を説明。こうしたなか、ビジネスとICTシステムを橋渡しするのが「要件定義」だと定義した。柴田氏は「要件定義がきちんとしていないと、使えないICTになる。すべてを盛り込むのではなく、経営の観点、業務の観点からきちんと優先順位を付ける必要がある」と語った。 続いてSI生産改革統括部 森田功氏は、日経コンピュータのアンケートを引き合いに、システムの品質の現状を説明した
ニュース | 開発文書の品質改善を目指す研究会が2011年7月に発足 2011.6.27_01
[ keyword： 品質管理， 研究開発， ソフトウェア ] 開発文書の品質改善を目指す研究会が2011年7月に発足 ソフトウェアの要求定義書や設計書といった開発文書の品質を測定可能にすることをねらいとした研究会「システム開発文書品質研究会（Association of System Documentation Quality；ASDoQ，略称アスドック）」が，2011年7月に発足する．これまで開発文書は，各社で標準フォーマットを定義したり，プログラムのボリュームに対するドキュメントのボリュームの割合が提案されるなど，形式については議論されてきたが，表現があいまいになっていないか，必要十分な情報が盛り込まれているかなど，内容に踏み込んだ検討はされていないという．同研究会は，システム（ソフトウェア）開発文書品質の定義とそれを測定し改善する方法を研究し，提案することを目標としている．各企業が
理系のための文書作成術(4) ―― 自分の「赤ペン先生」を持とう
あの女性タレント，デビュー当時は冴えない顔だったけれど，いつのまにか美人になったよね...．それと同じことが文書作成にも言える．今回は，自分の作成した文書を他人に査読してもらう効能について説明する．（編集部） 技術解説・連載「理系のための文書作成術」 記事一覧 第1回 開発文書を分かりやすく記述する 第2回 図表を表現手段として活用する 第3回 開発文書の書き方はしごとのやり方を示す 第4回 自分の「赤ペン先生」を持とう 第5回 設計レビューでするべきこと，してはいけないこと 第6回 仕事で文書を「書かされている」あなたへのメッセージ ●お知らせ 連載「理系のための文書作成術」が電子書籍になりました！ ご購入は「Tech Village 書庫＆販売」のページから． 読者の皆さんは，自分が書いた文章を，ほかの人に査読してもらう機会があるでしょうか？ 多くの女性は，人から見られていることを意識
仕様書の書き方って，習いました？ - 日経エレクトロニクス - Tech-On!
突然ですが，読者諸兄姉は，仕様書の書き方って，教わったことはおありでしょうか。あるいは，部下に教えたことはおありでしょうか。 日経エレクトロニクス 2007年2月12日号のGuest Paper（pp. 133-152）では，「仕様書の記述力を鍛える」と題して，フェリカネットワークスのソフトウエア・エンジニアの栗田太郎氏に，「形式仕様記述」という手法を使ったプロジェクトの体験記を執筆していただきました。 同社は「おサイフケータイ」などとして知られる携帯電話機向けの「モバイルFeliCa」の開発元で，そのICチップのファームウエア開発に当たって，「仕様をキッチリ書けるところは，書こう。実装者任せにしないようにしよう」という意識を徹底，高品質なソフトウエアの開発に成功しました。成果物は，NTTドコモの携帯電話機「903iシリーズ」の全機種に採用されるなど出荷数も多く，責任の重いプロジェクトです
詳細設計書が滅亡しない理由 - kagamihogeの日記
IT 業界というか SIer の枠組みの中で働いている人であれば、一度は詳細設計書ないし詳細仕様書というドキュメントを見たか書いたことがあるだろう。 Excel 方眼紙の悪夢 詳細設計書の話の前にちょっと触れておきたいのが「Excel 方眼紙」 これまでのプロジェクト経験とネットの情報を見る限り、詳細設計書はほぼ 100% コレで書かれている。Excel 方眼紙がどのようなものかは こんな感じ である。典型的な使われ方は 【図解!!コレが方眼紙Excelだ！】:島国大和のド畜生 がわかりやすい。 「Excel 方眼紙」でググるとわかのだが、コイツは猛烈に嫌われている。一発作り捨てならば、図や表を交えたドキュメントをそこそこ作りやすいという利点はある。プレゼンや紙印刷を考えないならば、個人差はあれど PowerPoint 並の使い勝手を覚える人はいる。 がしかし、Excel 方眼紙はそのメリ
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
日科技連|ソフトウェア品質|SQiP研究会
要求定義書と仕様書の海で溺れないための10分でできる要件変更対策
つれづれなる技術屋日記: 誰かが、仕様書/テスト項目の全体をチェックしないと