LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介しています。 どれくらい大評判だったかというと、2日間4セッションでしたが、エントリー数はのべ1000人を超え、実際の参加人数はのべ約900人。アンケートの回答は以下のとおり
テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
2011年6月10日、Evernoteを使用開始。 2014年9月19日、有料プランに加入。 2024年3月23日、クソみたいなメールが届く。 プラン、廃止 いつも Evernote をご利用いただき、ありがとうございます。このたびは今後の Evernote 登録プランに関する変更についてご案内させていただきます。 お使いの Evernote アカウントは Plus から Personal に移行されました。Evernote Plus など、一般のお客様に数年間ご利用いただけなかった従来の登録プランが廃止となったためです。この変更により、Personal プランで利用可能な機能すべてをご利用いただけます。 今後はAnnualの登録プランが現在の Evernote Personal プランの料金 129.99 USD/Yearに合うように更新されます。この料金は次の更新日である2024/4/
研究発表のスライドの仕上げの目的は、単に見栄えを良くすることではなく、伝えたいことが正しく・詳しく・分かりやすく伝わるようにすることです。スライドの推敲の技術を知って、実践的に身につけましょう。大阪大学大学院の教員であり、2021年10月に『卒論・修論研究の攻略本（森北出版）』を上梓した著者が実例付きで解説します。 スライドの推敲とは？文章がそうであるように、スライドもまた、「伝えたかったこと」をいつでも正しく伝えてくれるとは限りません。そして、正しく伝わるはずだ、という淡い期待を裏切られたときは、本当につらいものです。 文章を推敲するように、スライドにも推敲をかけましょう。ただし、スライドを推敲する際に、単にスライド中の語句を推敲するだけでは不十分です。スライドは、文章とは異なる表現形式だからです。 とはいえ、実は、著者の別記事で紹介した文章の推敲技術は、スライドの推敲にも使うことができ
小学生に教えるために編集者歴17年の父親が本気で考えた…｢きちんと伝わる文章｣を書く10のコツ ｢説明ができる｣とは｢生きる力がある｣ということ
「伝わる文章」とはどのようなものか 私はWEB媒体の編集者／ライターをかれこれ17年ほどやっている。日本語で情報を伝えるのが仕事だ。 ジャンルとしては長文の体験レポートを中心に扱ってきた。ライトな読み物で、書くのも簡単そうだと思われるかもしれない。いやいや、そうでもないのだ。それぞれのバックグラウンドを持ち観察力に優れた書き手が、五感をフルに使い数時間かけて体験取材をすると、情報量がとんでもないことになる。それを限られた字数で読者にわかりやすく伝えるのは、実は技術のいる作業なのだ。 また、私は特に編集部の中でも新人ライターを多く担当しており、書き慣れない人が書いた文章を一緒に直し、読み手に伝わる書き方をアドバイスする経験をずっと積んできた。 そんな私が、小学生の子供の中学受験によってあらためて「伝わる文章の書き方」を見つめ直すことになった。本稿ではその経験について少し語らせてほしい。
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。｜Fritz | Lead Product Manager @ Mercari
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が（たぶん） IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル（
どうやって校閲記者は調べているか
「著者から後書きに名前を入れていいか聞かれることはありますが、誤植が後で見つかったらと思うと怖いですね」。引用部分を探す苦労、事実確認はどこまでするか…出版の分野で活躍する校正・校閲者の方々に聞きました。... 「これは会社の財産ですね。ぜひ公開してほしい」 「校閲者や司書は泣いて喜ぶと思いますよ」 毎日新聞の校閲センター内で共有しているインターネットサイトのリンク集のことです。私たちの仕事に合わせて作ってきたので一般にどこまで役に立つか分かりませんが、そのような声をいただいたため、どなたでもアクセスできる部分などを公開することにしました。 このリンク集の始まりは2009年ごろ。米国の雇用統計や消費者物価指数など、一から調べると手間がかかる経済関係の情報を早く調べるためでした。そこからスポーツなどデータが豊富に使われる記事などでもリンクがまとまってあれば便利だということで徐々に分野が広がり
テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://speakerdeck.com/naohiro_nakata/technicalwriting
【翻訳】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分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
相手に誠実に、わかりやすい文章を書くための心がけをまとめました。 どういう思考プロセスからどんな表現が生まれるのか、参考として実例を紹介しています。実際に読み比べ、SmartHRの従業員として何かを伝えようとするときの、参考にしてください。 伝わる文章のガイドライン何を伝えるかによって、必要な情報の量や説明の粒度は異なります。 情報が不足していたり、逆に情報が多すぎたりすると、読者が意図を読み取れないことがあります。 読み手となる相手の状況（読む場面、事前知識など）を踏まえ、言葉にする内容や表現を厳選することが大切です。 目的に合わせて情報を取捨選択する読者の目線に立ち、コンテンツの目的に合わせて情報を取捨選択しましょう。 実例1：法律や業務に関わる記事目的業務に関係する「厚生年金保険」について正確に知りたいと思っている人に、わかりやすく内容を伝える。 Before日本の年金制度は、全国民
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
Pythonプログラミング入門¶ ▲で始まる項目は授業では扱いません。興味にしたがって学習してください。 ノートブック全体に▲が付いているものもありますので注意してください。
まえがき コードレビューの目的 大目的 小目的 チェックリスト 優先度高（大きな損失を生む問題・後からの修正が困難な問題） 優先度中 優先度低（システムに大きな影響を与えない問題・後からの修正が容易な問題） レビューを負担にしないために レビューサイズのコントロール 誰がレビューをするか 議論をどうまとめるか 批判と個人攻撃 レビュワー向けアドバイス Code author向けアドバイス 参考文献 まえがき コードレビューの有効性が説かれるようになって久しい。しかし、コードレビューをするべきという観念ばかりが先立ってしまい、何のためにコードレビューをするのか、どのような点をレビューするべきなのかといった、目的や進め方に対する意識が曖昧なケースも数多くあるように思われる[6]。コードレビューの目的を理解せずに惰性でレビューしているだけでは、いずれレビューそのものが形骸化し、単に承認のハンコを
こんにちは。 ご機嫌いかがでしょうか。 "No human labor is no human error" が大好きなネクストモード株式会社の吉井 亮です。 日本国内においても多くのシステムがクラウド上で稼働していることと思います。 俊敏性、拡張性、従量課金、IaS、セキュリティなどクラウドのメリットを享受しやすい所謂 SoE で多くの実績があるように感じます。 ここ1~2年は、社内基幹システム・情報システム、SoR 系のシステムのクラウド移行が本格化してきたというのが肌感覚であります。 クラウドでのシステムインフラ構築は従来のようにゼロから非機能要件定義を行っていくものではなく、ベストプラクティスをまず実装して少しずつ微調整を行っていくものと考えています。とはいえ、システムごとの要件は予め明らかにしておくことがインフラ構築においても重要になります。 クラウド上では出来ること出来ないこと
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
第0部 まずは「分かりづらい説明」を知ろう（p.14～） 第1部 口頭説明編（p.25～） 第2部 資料作成編（p.63～） 第3部 スライド作成編（p.81～） スライドのまとめ（p.115～）
アメリカの職場にいると、日本にいるときよりも身近でレイオフだとか、職を変えるというのを頻繁に見かける。先日もそういう場面があったのだが昔日本で働いていた時のことを思い出した。 ドキュメントを書く理由 日本のソフトウェア企業にいたときは、「納品物であるから」という理由以外にも、「人がいなくなったときに会社が困るから」という理由でもドキュメントを書くことが推奨されていた。しかし、少なくとも今の職場ではそんな理由でドキュメントを書くのは推奨されていないのに、なぜ問題にならないのだろうとふと思った。 うちのマネージャは、バディ制ににして、みんな休暇できるようにしようとは言っているが、多分本当に退職対策ではないと思う。 チームのメンバーが抜けたときも、「とても残念で、ワークロードをどうしようという問題はあるけど、彼女の門出を祝福しよう」言っていた。つまり、こちらでも「工数」は問題になるけど、「引継ぎ
成果物 https://github.com/ulwlu/dotfiles/blob/master/system/macos.sh このスクリプトに全ての設定と、設定可能なオプションをコメントで記載しています。誰でもこのスクリプトのコメントを外したり任意の値を入れる事で使用可能です。 世界中のいくつかのdotfilesにはmacos.shが存在し、ある程度のMacOSの設定自動化を実現しています。しかし何百と見た中で、全設定と設定可能なオプションを全て網羅して記載しているのは恐らく初です。 これらの設定は破壊的なものではなく、いつかアプデによりキーが有効でなくなっても壊れる事はありません。壊れるのは~/ApplicationSupport/Dockディレクトリ配下のファイルを移動したり、sqlite群に無効な値をいれた時のみです（後述）。 この記事は何か dotfiles Advent C
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
スクリーンショット これはなに 会社で「PR用の文章を人力でチェックする工数が重くて、めっちゃ残業が発生している。なんとか自動化できないか」との依頼を受け、Word等のファイルをGUIでそのままtextlintできるツールをちゃちゃっと作って社内公開しました。その結果、いい感じに社内で有効利用してもらうことができたので、外部公開に踏み切ることにしました。 github.com インストール＆設定 1. インストーラーでツールをインストールする GitHub上で配布しています。 https://github.com/gecko655/proofreading-tool/releases Mac版で「開発元が未確認のため開けません」が出た方へ https://support.apple.com/ja-jp/guide/mac-help/mh40616/mac を参考に、アプリケーションをセキュ
みなさんこんにちは。 資料デザインのリサーチや分析に取り組むパワーポイントのスペシャリスト、パワポ研です。 いつも企業が出しているパワーポイントの分析結果などを紹介しているのですが、本日は良いパワーポイントが見れる場所とその理由を紹介します。 どこで見れるのかずばり、経産省のHPです。以下のURLより「委託調査報告書」を確認ください。ご存じの方も多いかもしれませんね。 トップはこんなページになっています。 トップ的なページこの中で、例えば「令和4年度分の掲載一覧（PDF形式：48KB）」を押してみましょう。 令和4年度分の掲載一覧こんな感じのリストがずらっと並べます。エクセルでも同じようなものがダウンロードできます。正直見づらいですが、このリンクの一つ一つが調査報告書になっています。 何ですごいのか数と質です。 数のすごさ 数については、パワーポイント形式以外（ワード）の報告書もかなり混じ
サービシンクの名村が25年に渡るWeb制作のプロジェクトマネジメントで「テキストで情報を伝える」上で認識齟齬に至る点を洗い出した「誰がどう見てもそうとしか受け取れない文書術」のセミナースライドの2020年3月29日公開版です。 Web制作・システム開発に関わる人以外には事例等が分かりにくいかもしれませんが、日本語の弱点とそれを補うためのコツと答えを記載していますので、何かの参考になれば幸いです。
「VS Code Meetup」は、強力かつ軽量なオープンソースのコードエディター「Visual Studio Code」のミートアップです。今年もVS Code Meetup 主催の年次カンファレンス、「VS Code Conference Japan 2021」が開催されました。招待講演では、SF作家の藤井太洋氏が登壇。VS Codeで執筆を支援する機能拡張「novel-writer」の制作について発表しました。 『Hello, World!』で吉川英治文学新人賞を受賞したSF作家 藤井：お時間いただきまして、ありがとうございます。本日、「Visual Studio Codeで小説を書く」というセッションを持たせていただく、SF作家の藤井太洋です。それでは、プレゼンテーションを進めます。 まず簡単な自己紹介から。私は、2012年に『Gene Mapper』というサイバーパンク小説をセル
Excel設計書を抹殺したくて4年前にWiki設計書を導入したら、意外とちゃんと開発回ってた話。 - Qiita
初めましてこんにちは。 最近コードレビューの記事書いたら、Excelベースだったことを理由に Qiitaコメントとはてブで徹底的に燃やされたおじさんです。 いやね、僕だって使いたくて使ってるわけではなくてね、 できることなら使いたくないんですよ。 というわけで名誉挽回のために脱Excelできた話、 それも日本の三大悪三大風習に数えられるExcel設計書を抹殺した話を書きます。 (2/25修正：悪は言いすぎました。訂正します。） Growi 最高。 またの名をExcel方眼紙。 エクセルのセルの縦横を同じくらいの大きさに調整し方眼紙のようにして、 そこに設計書として文字と図と表を記載する方式。 メリット 一つのファイルに文字と図と表がまとめて記載できる テキストでは文字は書けても図と表が書けない Wordでは、文字と図表エリアとを2列表示するのが難しい できなくはないが面倒くさい UMLモデ
社内情報共有についての考え方 - An Epicurean
タイトルのようなエントリを社内に向けて書いたので、手直しして社外に放流するものである。 社内で情報共有フローやガイドライン整備などを進めている。ルールは少ないに越したことはないので「ルール作り」にはしたくなくて、考え方やガイドラインみたいなところに留めて、文化や共通言語を醸成していきたいとも考えている。 これは、今後組織が大きくなる上で、「スピードを落とさないため」に必要だと考えている。新しく入ってきた人が立ち上がりを早くパフォーマンスを発揮してもらえるようにしたい。 オンボーディングの整備は大事で、それもやっていかないといけない。でも今のフェーズではどうしても未整備の部分も多い。そういう荒地を楽しんで走破できる自走力があって、自分で決めて整備もできて、組織と一緒に成長してくれる人を採用していきたい。なので「自走しやすい環境」を整えたい。そのために必要だと考えている点が以下の3点です。 デ
リモートワークで仕事をしていると、Slack や Teams といった何かしらのチャットツールでコミュニケーションを取ることが多い。そうやって仕事を続けていく中で「こう伝えたらよりスムーズに話が進んだかな...」という後悔は多々あり、日々試行錯誤を続けている。 そうやって試行錯誤を続けていく中である程度テキストコミュニケーションを取る上でのフォーマットが定まってきた気がするので、箇条書きでまとめてみようと思う。（随時更新予定） prefix （接頭辞）をつける文章の先頭にその文章の目的がわかるような prefix をつけて、何のためにポストしたかを一目で分かりやすくする。例えば以下のような prefix をつけることがある。 【質問】→ 相手の返信が欲しい時 【共有】→ 返信は不要だが、内容は把握しておいてほしい時 【メモ】→ 返信不要で、後から検索できるよう残しておきたい時 箇条書きする
Google エンジニアリング・プラクティス ドキュメント
Google エンジニアリング・プラクティス ドキュメント このページは、Google Engineering Practices Documentation の非公式な日本語翻訳です。元のドキュメントは、クリエイティブ・コモンズの「CC-By 3.0」ライセンスで公開されています。 Google には、あらゆる言語・あらゆるプロジェクトをカバーする一般化されたエンジニアリング・プラクティスが数多く存在します。こうしたドキュメントは、私たちが長年に渡って開発してきたさまざまなベストプラクティスの経験が集結したものとなっています。オープンソース・プロジェクトやその他の組織でも、こうした知識から恩恵を受けられるかもしれません。そのため、私たちは可能な限り、この知識を公開するように努めています。 現在、以下のドキュメントが公開されています。 Google コードレビューガイドライン (Googl
障害報告書を書こう！ - Qiita
担当しているITサービスなどに何かしらのインシデントや障害が発生した時に、対処後のアクションとして報告書を提出して事象の内容を報告（レポート）する場合がある。 提出先は会社の偉い人だったりクライアントだったり。場合によってはユーザー向けに発表したり。事の顛末を報告して「今後同様のことを起こさないように努力します、ごめんなさい」をするのだ。どのように再発防止の努力するのかを書くものでもある。 主にクライアント向けのビジネス内容ではあるが、自分が使っているテンプレパターンを共有するので参考にしてもらえればと思う。1 全般的なポイント 心得のようなもの。次の点は留意してて欲しい。 淡々と冷静な説明をこころがける 当然のことながら事実は脚色しない。無駄な修飾も要らない。客観的な事実を簡潔に述べる。 例： ❌「一生懸命頑張って対応したが…」 ❌「寝ないで対応したが…」 ❌「本当の原因は…」 できるだ
万能ノートアプリ｢Notion｣をベンチャーが絶賛する理由…1000万ユーザー超の急成長には理由がある
多機能ノートツールの｢Notion｣が、じわじわと人気を集めている。全世界1000万人以上のユーザーがおり、すでに日本法人も始動している。 Notionを一言でいうなら｢何でもできるドキュメントツール｣だろう。メモやドキュメント、データベース、Wiki、タスク、プロジェクト管理からファイル管理まで。複数のクラウドツールに分散しがちな仕事に必要なあれこれを集約し、管理、共有できる。さらに、ドキュメントの一部をそのままWebページとして公開することも可能だ。 オンラインツールに感度の高い一部のスタートアップでは、すでにNotionを業務に取り入れて使い始めている。 ネットスーパーの垂直立ち上げサービスを提供する10X（テンエックス）社の事例から、｢業務で使うNotion｣の実例を見ていこう。
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
Dockerの概念や仕組みまではなんとなく理解できるもののDockerfileを書こうとするとスムーズに書けなかったり、そもそものDockerの基礎、あるいはコンテナ技術というものの基礎が抜け落ちていてDocker環境に移行できていないところも多いのではと思い、この記事を翻訳しました。 Source：The Docker Handbook by Farhan Hasin Chowdhury（@Twitter） 本記事は、原著者の許諾のもとに翻訳・掲載しております。 コンテナ化の概念自体はかなり古いですが、2013年にDocker Engineが登場したことで、アプリケーションのコンテナ化がはるかに簡単になりました。 Stack Overflow Developer Survey-2020によると、 Dockerは#1 最も望まれるプラットフォーム、#2 最も愛されるプラットフォーム、および
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。先日、このLINE Engineering Blogで「LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた」というタイトルで、1文を書くときに気をつけていることや手法について紹介しました。 前回の記事を簡単にまとめると「たくさんの文案を書いて、一番良さそうなものを選択することがとても大切です」という話を多くの例文を使って説明しました。まだ読んでいない方はぜひ読んでみてください。 今回の記事は、第2弾です。次のステップとして「1文では説明が終わらない文章をどのように組み立てていくとわかりやすいか」という話を、以下のような文章を例に説明していきます。 ここでは、このくらいの情報量の文章を「トピック」と呼びます。 第2弾を最後まで読む
Markdownでシーケンス図とかが書けるMermaid記法で業務フローを書いたら意外とイケたので自分なりのコツを紹介してみる | DevelopersIO
こんにちは、臼田です。 みなさん、業務設計してますか？(挨拶 今回はMarkdownでシーケンス図やフローチャートなどの図を記述できるMermaidを使って業務フローを書いてみたら、意外と書けたので自分なりのTipsを紹介したいと思います。 その前に 注意点として、まだMermaidを使い始めたばかりなので、「もっとこうしたらいいぞ」とか「こっちのほうがいいぞ」とかあれば建設的なフィードバックとしてSNSとかでいただけるとありがたいです。 あと業務フローって表現しましたが、人によって思い描く業務フローが違うと思うので、業務フローの定義に関するツッコミはご容赦ください。私が今回Mermaidで書いたのは以下の図です。(内容はブログ用に簡素化しました) この図のコードは以下のとおりです。(後ほど解説します) sequenceDiagram autonumber actor お客様 partic
2022/12/31 23:12追記 多数のおすすめを教えていただいたことで、知見が広まっだけでなく用途別に使い分けるのが良さそうだと気づきを得られたと思います 文書作成はObsidianのようなMarkdownがいけるエディタで、ちょっとしたメモにはKeep/OneNoteのどちらかでやるのが快適そうな予感はしています。が、正解がわかるのは流石に来年になってからでしょう。 実際にしっくり来たかの続報をいつか書きたい気はしていますが、増田は一期一会ですし予定は未定で終わるかも…ともかくありがとうございました。そして良いお年を。 2022/12/31 12:20追記 みんなのおすすめメモアプリを教えてほしい。今はEvernoteでやってるけど新しいアプリのことも知っておかないとな、と思ったので教えてくださいな 要件は以下 ・AndroidでもiOSでも編集可、ブラウザPCからでも編集できる
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
大手ITスタイルガイドがベースGoogleやMicrosoftなど大手IT企業の英語スタイルガイドの基準がベース。一般的な英語表記から外れません。
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita
質の高い技術文書を書く方法 - As a Futurist...
さようなら、全てのエヴァーノート - 本しゃぶり
プレゼンスライドがみるみる良くなる基本の推敲技術 -事例付き解説-｜石原尚（大阪大学教員）｜note
テクニカルライティングの基本 2023年版
伝わる文章 | 基本要素 | SmartHR Design System
Pythonプログラミング入門 — Pythonプログラミング入門 documentation
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
Pythonプログラミング入門 — Pythonプログラミング入門 documentation
コードレビューの目的と考え方 - osa_k’s diary
AWS システム構築 非機能要件ヒアリングシートを公開してみた | DevelopersIO
わかりやすい説明のための 10 の鉄則
アメリカの職場ではなぜドキュメントも無いのに人が去っても問題ないのだろう？｜牛尾 剛
Mac を買ったら必ずやっておきたい初期設定を、全て自動化してみた
社員用に作った文書校正ツールを一般公開した - gecko655のブログ
【極上パワポの宝庫】経産省の委託調査報告書には、なぜ日本で一番きれいなパワポが集まるのか｜パワポ研
誰がどう見てもそうとしか受け取れない文書術（公開版）
「Visual Studio Code」で執筆するSF作家 藤井太洋氏が作る物書きのための拡張機能
テキストコミュニケーションで意識していること｜ymdkit
Dockerハンドブック - 教会エンジニアの開発日記
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
LINE社内テクニカルライティング講座第2弾！1文では説明が終わらない文章を書くコツ
メモアプリの知見を貸してほしい（12/31 23:12追記）
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
IT英語スタイルガイド | IT英語スタイルガイド
togetter.com
twitter.com
trilltrill.jp
sndj-web.jp
c-v-d.shop-pro.jp
livefortoday.jp