ドキュメントを書かないことは「負債を生む」ということ - Qiita
本記事の要約 ドキュメントを書かない事は、企業やチームの「負債」になる ドキュメントを書かない事は、自身の学びや振り返りの「機会損失」になる そういう文化が根付く前に、負の連鎖を断ち切ろう！ はじめに 世の中のプロジェクトには、ドキュメントが足りていない、と感じています。 でも残念な事に、ドキュメントをどうしても書きたい人は「ほとんどいない」と思います。 その一方で「ドキュメントを書いた方が良い」という事は、 何となく分かっている人も多いと思います。 やりたくない事をやらなければならないのは、嫌ですよね。 そんな気持ちは分かりますが、これを機に一度改めてみませんか。 何故なら、ドキュメントを書かない事はチームに「負債」を生むからです。 勤め人ならば少なからず一度でも、体験した事があると思います。 「どうして必要な過去の資料が無いんだ」って。 あるはずの歴史の一端がソースコードからしか分から
アウトプットガチ勢が作った高速記事作成フレームワーク - Qiita
はじめに 本記事はアウトプットの心構えのカレンダー | Advent Calendar 2023の4日目の記事です こんにちは！！@Sicut_studyです！ 私はアウトプットの大切さを日頃から発信しており、実際にQiitaにたくさんの記事を投稿しています そんな中で、自分なりに高速に記事としてアウトプットできるフレームワークを使っているのでそのフレームワークについて紹介していきます アウトプットの大切さ まず言っておきたいのはアウトプットは質より量です 量が増えるとだんだんと質もあがります 私は駆け出しのエンジニアの方に普段から「100本記事を書けば人生変わる」と言っています。 そもそも世の中に100本記事を書いたことのある経験をしたことがある人はごく僅かです そんなごく僅かな人になれれば絶対人生が変わります。 多くの人ができないことをやり遂げられる。しかも記事という形で目に実力が見え
構成図を描く際に気をつけていること - NRIネットコムBlog
こんにちは、越川です。 皆さんは構成図を描く機会ありますか？ 僕の場合、内部のメンバーやお客様との議論の場で、構成図を描いて図解ベースで説明することが多いです。実際に描いてみると色々と考慮すべき点が多く、今回は自分なりに普段意識している点を言語化してみようと思います。 なぜ構成図を描くのか 構成図を描く際に意識している３つのこと 1. 導線 2. 引き算思考 1. 主役を決める 2. 読者を想定する 3. 高さや大きさを揃える さいごに なぜ構成図を描くのか 構成図のメリットは相手に伝えたいことをシンプルに伝えられる点だと思います。文章で書くと沢山書かなければいけないことが構成図を使うとスムーズに相手に伝わります。例えば、以下の文章を読んでみて下さい。 ユーザーはDNS登録されたFQDNへHTTPSアクセスする CloudFrontはBehaviorに指定されたALBにHTTPSリクエスト
「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ 書籍『エンジニアのためのドキュメントライティング』の概要
インフラエンジニア向けの書籍を取り上げ、著者と出会い、楽しく本を知り、仲間を作る場所である「インフラエンジニアBooks」。ここで、『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の翻訳を担当した岩瀬氏が登壇。まずは、本書籍の概要について話します。 本セッションの対象者と、セッションのゴール 岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。 余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルト
良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
FigmaとNotionでUML・経理処理・デザインまでAll in oneな仕様書を書いて、更新・共有を楽にしてる話 - Qiita
前提としての情報 単に「Figmaで要件定義のためのUMLも、外部設計のためのデザインも、内部設計のためのERDも全部つくるよ〜〜」という話をすると、ERD書くならデザインツールなんて使わないで、DBMSから自動生成できるツールとか使った方がいいじゃん、みたいな疑問が出るのは重々承知なので、そもそもこの形式に落ち着いた前提事項を書いておきたいと思います。 ご興味がなければ読み飛ばしてください。 筆者の仕事範囲 さて、冒頭で「事業会社でデザイナーとPMの狭間みたいな仕事をしてます」と書きました。キャリアの背景的には受託のPMっぽい仕事（厳密には違うんですが、本旨ではないので割愛します）→事業会社のインハウスデザイナー→現職という感じで、外渉から手を動かす所まで、必要ならなんでもします。 ざっくりいうと、機能の起案をして、経理などの関連部署に相談して、WBS引いて、UML書いて、画面遷移図書い
テクニカルライティングで技術をわかりやすく伝えよう！テクニカルライティング勉強会開催記 - LIVESENSE ENGINEER BLOG
先日、社内でテクニカルライティングに関しての勉強会が開催されました。 リブセンス社内の多数のエンジニアが参加し、大盛況となりました。この記事ではそんな勉強会の模様を紹介します。 概要 開催の経緯 エンジニアブログの記事を自信を持って書いてもらえるようになってほしい 良い文章とはどんな文章かの共通認識を作りしたい 講義の内容 テクニカルライティングの基本的な考え方を知る 伝える情報を整理する アウトラインを作る トピック単位で文章構成の骨組みを作る わかりやすく、簡潔な文章で書く 質疑応答 最後に 概要 今回の勉強会では、外部より仲田 尚央さん(@naoh_nak)に講師をお願いしました。テクニカルライティングの分野で多方面で活躍されている方です。「ヘルプサイトの作り方」という本の著者であり、「テクニカルライティング ✕ UX」をテーマにした勉強会の主催もされています。 https://ww
オンラインドキュメントと日本語全文検索
自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検
Python コードでアーキテクチャ図を生成できる Diagrams がめっちゃ便利！ - kakakakakku blog
「Diagrams」を使うと Python コードでアーキテクチャ図を生成できる．サポートされているアイコンセットがとても多く AWS や Google Cloud や Microsoft Azure もあれば，Kubernetes やプログラミング言語なども使える．試してみたけどめちゃくちゃ便利！まさに Diagram as Code だ✌️ diagrams.mingrammer.com セットアップ 「Diagrams」は Graphviz に依存しているため，macOS だと pip と brew ですぐにセットアップできる． $ pip install diagrams $ brew install graphviz 試してみた さっそく Examples を参考にアーキテクチャ図を作ってみた！ サンプル : AWS from diagrams import Cluster, D
GoogleのDesign Docsから学ぶソフトウェア設計 - Qiita
概要 Design Documentと聞くと何を想像しますか？ 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの？」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは？ Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて
わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
AWS のアーキテクチャ図を描きたい ! でもどうすれば良いの ? - 変化を求めるデベロッパーを応援するウェブマガジン | AWS
こんにちは ! テクニカルトレーナーの杉本圭太です ! 最近読んで面白かった漫画は「海が走るエンドロール」です。 私は業務でお客様に AWS の様々なトレーニングを提供しているのですが、コースによっては AWS を利用したシステムのアーキテクチャ図を受講者自身に描いていただく演習を取り入れており、よくこんな相談を受けます。 「どうやって AWS のアーキテクチャ図を描くのが正解なんですか ?」 AWS のアーキテクチャ図を描く状況は以下のように様々な場面であり、同じような疑問や悩みをお持ちの方も多いのではないでしょうか ? 詳細設計で構成図が必要 チームで wiki などに図を貼り付けて残したい 構成検討フェーズなどで図を見てディスカッションしたい ワークショップを試しながら理解を深めるなど自分のために描きたい そこで今回は AWS アーキテクチャ図をどうやって描けば良いか悩んでいる方へ、
【汎用ソフトスキル】ドキュメンテーションの続け方
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
ドキュメント駆動開発v2
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
継続的ドキュメンテーション: Github DiscussionsとADRのすすめ - LIFULL Creators Blog
こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。 会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど... LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。 多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。 LIFULLの開発現場にもこの
公式ドキュメントの読み方
「公式ドキュメントを読め」というのが急に話題になっていたので自分なりに整理してみました。 注意: そんなに真面目に推敲していません。フィーリングで書いているので実態に即してない部分もあるかも…… 公式ドキュメントとは何か あなたが使おうとしている道具 (ライブラリ、フレームワーク、プログラミング言語、ミドルウェア、コマンドラインツール、etc.)[1] は必ず誰かによって作られています。ある程度成熟した道具であれば通常、その作った人・組織自身によって公開されているドキュメントがあるはずです。これが公式ドキュメントです。 公式ドキュメントは、OSSにおいてはソースコードと双璧をなす最も信頼できる資料のひとつです。ソースコードが非公開の場合は通常、公式ドキュメントが最も信頼できる資料でしょう。 (以降はOSSを主に想定して説明します) たとえば…… Python のソースコードはGitHub上
ソフトウェアドキュメント作法 - maru source
こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました！ #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
大学生に『書くこと』の授業をしたときに 引き合いに出した本 / books on writing for students
ドキュメントを改善するためのはじめの一歩
