「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
情報共有ツール DocBase(ドックベース ) | ストレスフリーなドキュメント共有ツール
会議の際のペーパーレス化も進みました。週次の進捗会議のときに、かつては毎回資料を印刷する手間がありましたが、「基本DocBaseを見る」という今の形に変えたらすごく楽になり、アーカイブとしても便利なので過去の資料の確認なども楽になりました。 オイシックス・ラ・大地株式会社 関裕子様 あまり機能をつけすぎず、書く・探すにフォーカスしたシンプルなUIになっているのがよかったです。他に高機能なツールもありますが、ツールの使い方を学習するのに時間をかけるのはもったいないなと。DocBaseの編集画面は1、2日使えば簡単に覚えられますよね。 株式会社LINICA 大島希美様 チーム内の知識の偏りがなくなりました。「知ってる人しか知らない」ケースが減ったのかなと。「聞かれる側」としては質問を受ける回数が非常に減るので、そのぶんやりたいことをやる時間に回せるようになりました。 株式会社マイナビ 有田大志
会社でテクニカルブログを書くために - クリエーションライン株式会社
はじめに こんにちは。Cloud Solution Division ＆ Data Platform Team所属の山森です。 普段はMongoDBチームのテクニカルサポートを担当しています。今年で社会人12年目になります。 前職含め、新入社員のころからずっとインフラと運用の畑で働いており、過去にはお客様のGoogle Cloud環境の保守も担当していたことがあります。 昨今、テクニカルブログを書くことが求められているITエンジニアは多いのではないでしょうか。弊社内でもブログ執筆が推奨されています。しかし、書くことが大事という共通認識はあるものの、思ったよりも投稿件数が伸びない実態があります。 そこで、ブログ公開までにどのようなプロセスを踏んでいるか、アウトプットしてみることにします。会社でテクニカルブログを書きたいけど、何からすればいいのかわからない方たちの手引きになるかと思ったからです
DB設計の共有で疲弊してない？dbdocsのすゝめ
DB設計の管理や作成に疲弊してません？こんにちは。ukmshiです。今日はDB設計の共有と管理に便利なツール、dbdocsについてお話しします。dbdocsを使えば、設計の可視化や共有がめちゃくちゃ簡単になるんです。今回は、その魅力と利点、そして実際の使い方について詳しく説明します。 dbdocsとは？ dbdocsは、コードベース（DBML）でDB設計を管理し、URLで共有することが可能なツールです。データベースのテーブル構造や関係性を可視化し、それを他のチームメンバーやステークホルダーと手軽に共有することができます。 DBMLについてはこちらを参考に dbdocsの利点 dbdocsの利点について詳しく見ていきましょう。 無料 まず最初に、dbdocsは基本無料です。コストを気にせずに利用できるので、チームの誰もがアクセス可能です。 コードベースで管理 dbdocsはコードベースでDB
メモアプリの知見のお返しにきた
去年の大晦日に「メモアプリの知見を貸してほしい」という増田を書いた者です。750超のブックマークと注目をいただきまして大変感謝しています。 https://anond.hatelabo.jp/20221230142549 あれから半年経過してみて自分の使うメモアプリが定まってきただけでなく、メモの意識およびスタイルに変革が生じました。これを、皆さんからお借りできた知見の「お返し」としてご報告したいと思います。 「中身に興味無いけどブコメしたいからブクマした」という人は、簡単に作れそうな激辛料理を教えてください。最近自炊が楽しいもので…中華ばっかりですが。 コメントが「メモの意識変革」をくれましたブコメは270件、増田のトラバは50件と膨大なアドバイスや激辛スナック情報を頂いて、まずは発見がありました。 ある人が「タラタラしてんじゃね〜よ は激辛？」と聞いてきた折に「自分は激辛とは思ってない
中央大学ASC ライティング・ラボ - 資料
中央大学アカデミック・サポートセンター ライティング・ラボが編集・発行した「レポートの書き方資料」をお届けします。 この資料は、ライティング・ラボのセッションでよく相談を受けるアカデミック・ライティングの５つのポイントを整理したものです。初めてレポートを書かれる方、書き方に不安がある方にむけて、ラボのチューターと教員がレポートの書き方をわかりやすく解説しています。 PDFファイルを、下記URLからダウンロードできます。 ぜひレポート・論文の執筆に役立ててくださいね。（2021年9月1日） https://bit.ly/3xFtZVl 【目次】 １．レポート・論文の構成とレイアウト ２．序論・本論・結論 ３．パラグラフ・ライティング ４．引用のマナー ５．図表の扱い方
読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
Introducing Hermes, An Open Source Document Management System
TerraformInfrastructure as code provisioning
HashiCorp、ドキュメントの作成／レビュー／共有などを容易にする「Hermes」ドキュメントマネジメントシステムをオープンソースで公開
HashiCorp、ドキュメントの作成／レビュー／共有などを容易にする「Hermes」ドキュメントマネジメントシステムをオープンソースで公開 TerraformやVagrantなどで知られるHashiCorpは、「急成長するグローバル企業や遠隔地に拠点を置く企業にとって、書く文化は必要不可欠なものだと考えています（we also believe a culture of writing is a necessity for a fast growing, global, remote-oriented organization.）」として、同社内でも文書による情報共有文化が積極的に行われていると説明しています。 その同社が社内で開発し利用しているドキュメントマネジメントシステム「Hermes」を、オープンソースとして公開しました。 We are pleased to announce th
テクニカルライターよ概念図を描くのです 〜テクニカルライターのためのイラストテクニック２〜 / cybozu illust technique2
ドキュメントでは、「モノや人の関係を明確に表わす」「複雑な流れをわかりやすく説明する」といった場面がたくさん出てきます。概念図は、言葉だけでピンとこない複雑な関係も、わかりやすく伝えることができます。 本セッションでは、テクニカルライター向けに概念図を描くテクニックをご紹介します。
ナレッジマネジメントを組織に定着させるための提案｜國光俊樹
この記事はGoodpatchアドベントカレンダー2022の23日目の記事です。 突然ですが、私は昨年「ナレッジマネジメント」領域の新規事業を立案し、リサーチや価値検証を行いました。結果としてはβ版を複数社に導入していただきながら行った価値検証を経てクローズという判断になってしまったものの、そのプロセスを通じて様々な組織におけるナレッジマネジメントの状況や課題感、そしてベストプラクティスまで多くの知見を得ることができました。 今回はそういった経験を土台として、これまで発信の主テーマにしていた「UXデザイン」や「サービスデザイン」の領域ではなく「ナレッジマネジメント」というテーマで記事を執筆することにしました。 この記事では、組織としてナレッジマネジメントを推進する時にどのような観点や考え方が必要なのかを紐解いていけたらと思います。 (組織の状況やカルチャー、事業形態などによっても最適なHOW
コーディングのようにノートを取る技術 - Qiita
はじめに 何かを学習するとき、ノートを取っているでしょうか？ 小学生の頃や中学生・高校生の時の「ノート」は紙に手書きだったかと思います。 しかし、最近になってからはパソコンを使ってノートを取る、という選択肢が増えました。 その変遷の中で生まれたパーソナル・ナレッジ・マネジメント(Personal Knowledge Management) という考え方があります。 その考え方を共有できたらと思います。 直感的なデジタルノート術の原罪 ケース1: ひたすらに手を動かす 学生の頃、黒板に書かれた内容をそのまま必死にノートに写している人がいたのを覚えていますか？ また、その人は成績が高かったでしょうか？ たいていの場合、成績は乏しい人が多かったと思います。自分もそのタイプでした。 手を動かすだけのノート術の不幸な点は、「考える」というアクティビティが行われないため、本当の意味で筋肉を動かすだけと
伝わる文章 | 基本要素 | SmartHR Design System
相手に誠実に、わかりやすい文章を書くための心がけをまとめました。 どういう思考プロセスからどんな表現が生まれるのか、参考として実例を紹介しています。実際に読み比べ、SmartHRの従業員として何かを伝えようとするときの、参考にしてください。 伝わる文章のガイドライン何を伝えるかによって、必要な情報の量や説明の粒度は異なります。 情報が不足していたり、逆に情報が多すぎたりすると、読者が意図を読み取れないことがあります。 読み手となる相手の状況（読む場面、事前知識など）を踏まえ、言葉にする内容や表現を厳選することが大切です。 目的に合わせて情報を取捨選択する読者の目線に立ち、コンテンツの目的に合わせて情報を取捨選択しましょう。 実例1：法律や業務に関わる記事目的業務に関係する「厚生年金保険」について正確に知りたいと思っている人に、わかりやすく内容を伝える。 Before日本の年金制度は、全国民
チーム開発で活きる調査メモのすすめ
はじめに 自分が知らない何かを調べる時、どの様に調べていますか？ ソフトウェア開発では、自分やチームが有している知識で解決できる問題もあれば、現状の知識だけでは解決できない問題も多くあると思います。 その様なシーンで行うことは、問題を解決するために必要な知識や手法を調べることだと思います。 せっかく時間をかけて調べたのなら、その過程を記録しチームに共有できると良いなと思っているので、この記事では調査内容をメモする際の観点を文字にしてみようと思います。 調査メモの観点 前提 今回は例として以下の問題（課題）を解決するために調査をし、解決するための実装をする過程をメモとしてまとめていきます。 調査と解決を同時に進めたいことが多いと思うのでこの様な前提としています。 Cypress のテストレポートを生成し CI でクラウドストレージに保存したい monorepo 構成のリポジトリになっており、
英語が苦手な人が英文Writingを学ぶにあたっておすすめの本五選｜Yuki Nakazato
Amazonのミーティングはとても奇妙な形で行われることが多い - ミーティングの最初にドキュメントを参加者が黙読するのだ。議論は全員が読み終わったことを確認してからスタートする。基本的に文章を読まずにいきなり発言し出したりということは許されない。大人数が一つの部屋に集まり、一つの文章を黙って読む姿は結構シュールである。 私はこの奇妙なミーティングをする会社に7年ほど勤めていた。こういった環境で生き残るには人に読ませる、よいドキュメントを書かねばならない。しかもアメリカで働いているのだから当然英語で書く必要がある。しかしながら私は帰国子女でもなく、特段英語が得意というわけでもない。最初の頃に書いたドキュメントは複数人にレビューされていつも真っ赤っかになっていて、そのマークアップの量を見ては鬱々としたものである。が、小さな子供とVisa問題を抱えて異国の地でクビになるわけにもいかない。英語弱
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
議事録を簡単に構造化(っぽく)する方法｜とあるコンサルタント
はじめに議事録、取ってるぅ？ そろそろ新人は現場に配属され始めた頃だろうか。 「議事録取っといてよ」とか軽く言われて頑張って作ったら、赤字まみれに添削されるのが通過儀礼。 だいたい新人が最初に任される仕事だと思う。 ところが、議事録を真っ当に取ろうとすると日本語能力、プロジェクトへの理解、構造化力とかが試されるので、割と高度なスキルの複合が求められるのである。 というわけで、議事録を簡単に作るコツを１つ伝授したい。もちろん、習得のためには訓練が必要なので、この記事ではTips程度の話だけど、結構便利だと思う。 実用系スキルなので最後に課金枠を作っておくが、課金枠に中身はない。 君はおひねりを落としてもいいし、落とさなくてもいい。 そもそも議事録とは議事録とは、議事を記録したものである。 一般に会議を行った際の議論の展開と結果を示すもので、発言を一字一句名前付きで記録するものは特に逐語録なん
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
エンジニアのためのドキュメントライティング / Docs for Developers
良質な技術記事を量産する秘訣 / #MeetsPro
