テクニカルライティングの基本 2023年版テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://sp…
AWS Well-Architected ドキュメントが読みやすくなりました！！（AWS Well-Architected ドキュメントの歩き方2022） | DevelopersIO
AWS認定トレーニング講師の平野@おんせん県おおいたです。 さて、2021年に下記のような Well-Architected フレームワークのブログを書きました。 最近AWS Well-Architectedのドキュメントがアップデートされましたので、それに伴いブログも新しくリリースしました。 おもな変更点 ドキュメント構成の改善に対応 ドキュメント自体が読みやすくなりました（詳細は後述）。それに対応して、内容を変更しました。 新しい柱への対応 2021年12月に「持続可能性の柱」が追加されましたので、この新しい柱についての記事を追記しています。 尚、2022.1.9時点で日本語化されておりませんので ブログ内の見出しは、私の方で日本語訳したもの 各リンク先は英語ページ となっておりますので、ご了承ください。 はじめに AWS Well-Architected フレームワークとは AWSと
AWS Well-Architected ドキュメントが読みやすくなりました！！（AWS Well-Architected ドキュメントの歩き方2022） | DevelopersIO
AWS認定トレーニング講師の平野@おんせん県おおいたです。 さて、2021年に下記のような Well-Architected フレームワークのブログを書きました。 最近AWS Well-Architectedのドキュメントがアップデートされましたので、それに伴いブログも新しくリリースしました。 おもな変更点 ドキュメント構成の改善に対応 ドキュメント自体が読みやすくなりました（詳細は後述）。それに対応して、内容を変更しました。 新しい柱への対応 2021年12月に「持続可能性の柱」が追加されましたので、この新しい柱についての記事を追記しています。 尚、2022.1.9時点で日本語化されておりませんので ブログ内の見出しは、私の方で日本語訳したもの 各リンク先は英語ページ となっておりますので、ご了承ください。 はじめに AWS Well-Architected フレームワークとは AWSと
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ - Qiita
システム開発にドキュメントは欠かせません。ドキュメントが得意になれば活躍の幅が大いに広がりますよね。 この記事では、まず冒頭でドキュメントの作成に求められると思うことを整理した上で、そのスキル獲得に役立つと思われる記事や書籍を集めてみました。もちろん他にもあると思うので、もしお薦めのものがあれば是非コメントで教えて下さい 更新履歴 ・2021/04/16：文章術系にリンクを追加しました。 ・2020/11/28：文章術系にリンクを追加しました。 ・2020/07/24：文章術系にリンクを追加しました。 ・2020/05/24：文章術系にリンクを追加しました。 ・2020/05/14：スライドデザイン系にリンクを追加しました。 ・2020/04/29：スライドデザイン系にリンクを追加しました。 ・2020/04/17：文章術系にリンクを追加しました。 ・2020/04/12：関連するTwit
LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介していま
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。｜Fritz | Lead Product Manager @ Mercari
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が（たぶん） IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル（
信用できる社内 Wiki をつくるために守ってほしい、たったひとつのルール - 無印吉澤
このページについて この記事は、以前書いた「社内Wikiに情報を書くときに守ってほしい、たったひとつのルール」の続編です。前回は、個々のページをどう書くべきかという話をしましたが、今回は社内 Wiki 全体を信用できるものにする方法について考えます。 muziyoshiz.hatenablog.com 想定する環境 この記事は、ソフトウェア開発プロジェクトに関する Wiki が社内にあって、そこに各人がドキュメント（仕様書や手順書など）を書けるようになっている環境を想定しています。 私自身、ソフトウェア開発のときしか Wiki を使わないので、具体例もそのような環境に寄っています。ただ、ある程度は社内 Wiki 全般に通じる話かと思います。 ルール：「更新され続ける」ページと「更新されない」ページをはっきり分ける ここ1年ほど社内プロジェクトをいくつか渡り歩いていたのですが、個人的には、こ
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
Redmine で技術仕様書を書こう
はじめまして！ 株式会社 Aiming の土井です！ エンジニアをやっております！ 今回の開発者ブログでは、情報共有ツールとしての UML の活用方法について、現場での取り組みをご紹介させていただければと思います！ 技術仕様書の“図” どうやって書いてますか？ 株式会社 Aiming では、プロジェクトの Wiki やバグトラッキングに Redmine をメインに使っています。みなさんも既にご存知だったり、実際にバリバリ活用されていることとおもいます。 また、企画仕様書、技術仕様書などは Redmine の Wiki やエクセルに代表されるオフィススイート等を活用して作成しますが… 図の表現を求められるような仕様書を作る時に、どうやって作成しようか悩んだことはありませんか？ 標準ペイントソフトで頑張って作成 オフィススイートに含まれる、ドローツールを使って図を作成、画像吐き出し というケー
文章に向いてない構造をいかに文章に向いた構造に直列化するかが大事 - きしだのHatena
Software Design 12月号の特集が「なぜエンジニアは文章が下手なのか？」というタイトルだったので、読んでみたら、ちょっと残念な内容だった。 「それは文章で書くべき情報なのか」という章があって、直列化した論理構造であれば文章には書きやすいけど、分岐やループがあるような構造だと書きにくいということが書いてあった。そこで文章化しにくい構造の例として地図があげてあって、暗にそういう構造は文章化をやめて図であらわせと言っているように読める。 けれども、図に書いたところで、書く側は文章化から逃げれて満足かもしれないけど、それを読み取る側は結局どこかから順番に解釈していく必要がある。図に逃げるのは、読み手に責任を押し付けているだけだと思う。 で、「ですから文章を書く前にまず論理構造を考える必要があります」と続いていて、では考えた論理構造が「文章に向かない論理構造」だったらどうするの？逃げる
【翻訳】Gitをボトムアップから理解する
John Wiegleyさんの "Git from the bottom up" を翻訳しました。 元PDFはこちらからダウンロードできます： http://newartisans.com/2008/04/git-from-the-bottom-up/ 元記事のライセンスがクリエイティブコモンズのBY-SAであったため、この翻訳もBY-SAとなります。 ライセンスを守って自由にご利用ください。（詳しくは記事内の最初にも書いてあります） 翻訳ミスの指摘や改善の提案等があればブログコメントやTwitter(@oshow)などで遠慮なくどうぞ。 Git をボトムアップから理解する Wed, 2 Dec 2009 by John Wiegley 私が Git を理解しようと調査した時、高級なコマンドの視点から眺めるよりボトムアップ式に理解することが役立った。そしてボトムアップ視点で見る Git が
上司が“唸る”報告書 の書き方｜５つの具体的なテクニックや文例集など
1.報告書の構成 報告書とは、上司や関係者に必要な情報を提供するための文書のことです。３層構造（標題→内容要旨→詳細内容）で、情報の整理や要約をしていきます。 例えば、日時、場所、目的、内容等について、情報を簡潔に記入します。 また、所感は記入する場合と、しない場合があります。その場の細かなニュアンスを伝えたほうが有効な場合には、所感も書くようにします。 【報告書（例）】 〔pdf〕打ち合わせ報告書 〔pdf〕営業報告書 1-1.報告書の全体構成 注意すべき点は、以下の三角形の図のように、「標題」は「内容要旨」（打ち合わせ内容）の要約、 「内容要旨」は「詳細内容」（ヒアリング事項等）の要約という３層構造を理解することです。 実際、報告書を上から（標題から）順に書こうとするから難しいのであって、 報告書の説明文（詳細内容から）順に書いていけば、割と楽に書けます。 【報告書の構造（下位にいくほ
わかりやすい技術文章の書き方
誰が読むのか。 読み手にどんな感想を持ってもらいたいか。 読み手はどれくらいの予備知識を持っているか。 読み手はどんな目的で、何を期待して読むのか。 読み手が真っ先に知りたいことは何か。 レポート・論文とは何か 問いが与えられ、または自分が問いを提起し、 その問題に対して明確な答えを与え、 その主張を論理的に裏付けるための事実・理論的な根拠を提示して、主張を論証する。 標準的な構成要素とは何か レポート・論文の構成は、 概要 序論 本論 論議 という要素が標準的である。次にそれぞれの要素について簡単に見てみる。 概要 論文全体を結論も含めて、すべて要約する。 序論 本論で取り上げる内容は何か。 その問題をどんな動機で取り上げたのか。 その問題の背景は何か。 その問題についてどんなアプローチを取ったのか。 本論 調査・研究の方法・結論 論議 自己の議論・結論を客観的・第三者的に評価する。 そ
5分で人を育てる技術 (25)“文書が上手いと言わせる”5つのテクニック(中篇)：芦屋広太一つ...
・先方より，当方が提示した処理画面の操作性が問題なので，見直してほしいとの要望があった。 ・上記については，当方にて検討することで了承いただいた。 ・また，先方から，社内の情報提供に使いたいので，弊社が提供するシステムの機能と画面イメージをメールで送ってほしいとの要望があった。 ・上記については，後日メールする旨返事をした。 ・東氏より，当方のシステムを使ってみたが，非常に分かりやすいとの感想があった。弊社のシステムは特に問題ないのではないかと思われる。 ・戸塚氏からは，上司に説明したところ，テストについてもよろしくお願いしたいとの指示があったとの話があった。 ・これに対し，当方からは，一緒に相談しましょうと回答した。 ・次回の打ち合わせは来週の水曜日くらいとの話になったが，その日は東氏の都合が悪いかも知れないとの話になり，結局，その場では決められなかったため，後日調整しましょうという話に
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
GitHub - 1f408/cats_dogs: CAT'S DOCument System
テクニカルライティングの基本
標準教科書シリーズ お問い合わせ窓口
http://www.lpi.or.jp/linuxservertext/
ほんのすこし書き方に注意すれば、あなたのドキュメントはさらに分かりやすくなる！