情報の見つけやすさを追求する - 社内ドキュメンテーションの階層整理術 - KAKEHASHI Tech Blog
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
ITエンジニア向けのトレンド情報 | Forkwell Press （フォークウェルプレス）
アーカイブでは視聴者からのQ&Aを見ることができます ドキュメント文化を浸透させる方法 おすすめのドキュメント管理ツール ドキュメントがない状態での引き継ぎ 運用しやすいドキュメント構造とは 増えすぎたドキュメントの管理方法 ドキュメントを残さないシニアエンジニアへの対策 ドキュメントへの苦手意識を克服する方法 誰もドキュメントを読んでくれません 複数人でドキュメント管理するコツ 本記事のTopics 書籍の概要・構成 おすすめの書籍 読み手の理解 ドラフトの執筆 フィードバックの収集と組み込み ドキュメントの品質測定 日本語を学べる書籍 ドキュメントは開発側の生産性とユーザーの利便性を高めるもの。ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。 本書は、経験に長けた執筆者たちがドキュメ
FigmaとNotionでUML・経理処理・デザインまでAll in oneな仕様書を書いて、更新・共有を楽にしてる話 - Qiita
本記事は Figma Advent Calendar 2022 16日目の投稿です。 仕様書を作るとき、あの情報はこのツールで書いたほうが楽、みたいな感じで、あっちこっちに情報が散逸することがありますよね。 かくいう私も、事業会社でデザイナーとPMの狭間みたいな仕事をしていまして、UMLだのデザインだの、複数のツールを跨いで作業をすることが多かったのですが、最近は安定してFigma＋Notionで作業をしています。 これはデザイナーなのでFigmaの使い方に慣れている、ということもあるんですが、Figmaの自由度の高さや、Notionの情報統合性の高さ（この辺は後述します）が筆者の仕事範囲と大変に相性が良く、今の所ここがベストという形に落ち着いているので、軽く紹介してみようと筆を取りました。ご興味があれば読んでください。 TL;DR（この記事のあらすじ） エンジニア・非エンジニア・社内外い
[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? 更新情報（2025年4月5日） 37万回以上の閲覧、1,500件を超える「いいね」、そして1,700件以上のストックをいただき、心より感謝申し上げます。 多くの方に読んでいただいたことで、現場での活用や共感の声を多数いただきました。 今回の更新では、読者の皆様から寄せられたフィードバックをもとに、より実践的な内容を追記し、一部の表現をリライトしました。 特に「非機能要件」「移行・引継ぎ」「保守体制」に関する項目については、現場で実際に起きやすい課題に対する解決視点を強化しています。 今後も内容を継続的にブラッシュアップしながら、現場で本
![[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/45987abf041dfdc05d3bb195d835d5422e9c0408/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fqiita-user-contents.imgix.net%252Fhttps%25253A%25252F%25252Fcdn.qiita.com%25252Fassets%25252Fpublic%25252Farticle-ogp-background-afbab5eb44e0b055cce1258705637a91.png%253Fixlib%253Drb-4.0.0%2526w%253D1200%2526blend64%253DaHR0cHM6Ly9xaWl0YS11c2VyLXByb2ZpbGUtaW1hZ2VzLmltZ2l4Lm5ldC9odHRwcyUzQSUyRiUyRnMzLWFwLW5vcnRoZWFzdC0xLmFtYXpvbmF3cy5jb20lMkZxaWl0YS1pbWFnZS1zdG9yZSUyRjAlMkYyNDE5MDklMkY1ZGU1MmRjNTAzODc4N2IzNWZjOTJkODhiNDY4ZmM3YTI2OTM2NjI1JTJGeF9sYXJnZS5wbmclM0YxNjY0NzYzNzQ4P2l4bGliPXJiLTQuMC4wJmFyPTElM0ExJmZpdD1jcm9wJm1hc2s9ZWxsaXBzZSZmbT1wbmczMiZzPTgwOTA2N2M4MzdjYWExNWMzYjNiZjlkOGE4ODQzMzIz%2526blend-x%253D120%2526blend-y%253D467%2526blend-w%253D82%2526blend-h%253D82%2526blend-mode%253Dnormal%2526s%253D0a0e803c6b6e4c50d0467dc3582bd023%3Fixlib%3Drb-4.0.0%26w%3D1200%26fm%3Djpg%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk2MCZoPTMyNCZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMxRTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LXBhZD0wJnM9NzE1Zjc2MTRjYTk2OWVlNzc2NmYxOTk5OTQzYjQzNjc%26mark-x%3D120%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTgzOCZoPTU4JnR4dD0lNDBzeWFudGllbiZ0eHQtY29sb3I9JTIzMUUyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1wYWQ9MCZzPTMxZDY5NThkZmJiYTlkYzBlZGMxNjBjN2I2ZTY5Mzg0%26blend-x%3D242%26blend-y%3D480%26blend-w%3D838%26blend-h%3D46%26blend-fit%3Dcrop%26blend-crop%3Dleft%252Cbottom%26blend-mode%3Dnormal%26s%3D4f27d46ef16f3a13ec172558b5a2c0ec)
現代文書の構造 (La structure des documents modernes) - Stellar
文書を記述する際に、構造――ここでは見出しなどを指す――を機械が可読な形で行うことに意味はあるだろうか。 前回の続きといえば続き。 squeuei.hatenablog.com 前提 scrapbox.io 使わない文書構造の宣言に意味があるのか？ 「文字が大きくなって格好いい」以上の意味がない 使わないのにせっせと構造を宣言しているの、マジで意味わからん markdownはとにかくデカイ文字が簡単に書ける事が便利なだけなのでは？ 宣言した文書構造を有意義に使う方法がスクリーンリーダーと索引生成以外に何かあれば教えて欲しい #で<h1>や<h2>になる文書構造化がしたいと言いつつ、実はデカイ文字を書きたいだけ 反論 markdownが万能でも素晴らしい完全無欠のものでもないというのは理解する。 が、しかし、文字が大きいことと、構造上の意味を持つこととは違う。今価値がないからと言って、将来に
データベースのドキュメント管理を自動化した話 - estie inside blog
こんにちは、今回はデータ基盤構築を担当しているmarushoがお送りします。 今日はestieで実践しているデータベースのドキュメント管理方法をご紹介します。 はじめに 独自成長していくデータベースたち 失われたドキュメント どうすれば低コストなドキュメント管理ができるのか そして生まれた、schema collectorという自動化ツール SchemaSpy Mysql diff Priv Page ECS タスクスケジューラ ドキュメントを腐らせない おわりに はじめに estieはオフィスを中心とした不動産データを取り扱うスタートアップ企業です。 estie（オフィス探しサービス）とestie pro（不動産事業者向けデータプラットフォーム）の2つのサービスを運営しています。 詳しくは、こちらの記事をご覧ください。 inside.estie.co.jp estieでは、不動産に関する
データベースドキュメント生成コマンド tbls 更新情報 ( PostgreSQL publicスキーマ表示仕様変更/Amazon DynamoDB対応/goccy ware etc) - Copy/Cut/Paste/Hatena
ここ最近tblsのアップデートエントリを書いていなかったのですが、最近変更をいくつか行いました。 このまま放置するとちょっと紹介しきれなくなりそうなので、ここら辺で放出しておこうと思います。 紹介時点のtblsのバージョンはv1.29.0です。 PostgreSQLでの public. スキーマ表示仕様変更 tblsでは、もともとPostgreSQLの public. スキーマ（ schema_name.table_name.column_name の schema_name ）だけ特別に非表示にしていました。 こうなっていた理由は、私がPostgreSQLでのスキーマを意識した運用経験がなかったことに寄る部分が大きいです。「デフォルトだから非表示で良いだろう」と。 ところで、tblsにはlintの機能があります。「テーブルカラムにコメントが書かれているか？」とか「外部キーの参照元にIND
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜安野貴博
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
plant_erd - ER図をPlantUML用にエクスポート
UMLをテキストベースで記述できるPlantUMLを使っている方は多いのではないでしょうか。クラス図を流用する形でER図も描くことができます。そして、データベースはすでにあり、そこからPlantUML用に出力できればいいのに、と考えている方もまた多いでしょう。 そんな方にお勧めなのがplant_erdです。各種データベースに対応したER図エクスポートソフトウェアです。 plant_erdの使い方 出力した内容をPlantUMLで表示しています。 plant_erdはSQLite3、MySQLそしてPostgreSQLに対応しています。各データベースの内容をそのままPlantUML向けに出力が可能です。特定のテーブルだけを出力対象にもできます。リレーションも再現され、データベース構造をドキュメントに書き出すのにぴったりです。 plant_erdはGo製のオープンソース・ソフトウェア（MIT
ドキュメント技術とプログラミング言語の相似について - golden-luckyの日記
よく知られているように、ドキュメントには「構造」があります。 WebページではHTMLとCSSにより構造とスタイルを分離するべきとか、Wordでは書式設定をスタイルとして定義して使うことで構造とスタイルを分離するべきとか、ドキュメントの「べき」論で必ず言及される「構造とスタイルの分離」における「構造」です。 昨日までの話ではPDFにもドキュメント構造というのが出てきました。あれは、この「構造とスタイルの分離」というときの「構造」とは別物なので注意してください。 たぶん、PDFのドキュメント構造には、「ドキュメントを表すデータ構造」くらいの意味合いくらいしかありません。 一方、ドキュメントの話において「構造とスタイルの分離」というときの「構造」は、もうちょっとこうなんていうか、セマンティックな話です。 データをどう構成するかではなく、ドキュメントで表したい意味をどう構成するか、という話。 し
Qiita:Teamからesa.ioに乗り換えました - LCL Engineers' Blog
Webエンジニアの横塚です。 皆さんは情報共有ツールは利用しているでしょうか。 LCLエンジニアチームでは先日、以前から利用していたQiita:Teamからesa.ioに移行することにしました。 移行の背景と、実際に移行してみてどうだったかを簡単に紹介したいと思います。 teams.qiita.com docs.esa.io 移行しようと思った理由 Qiita:Teamは本来やりたかったwiki的な使い方にあまり合ってなかった LCLでは、システム仕様や、共有しておきたい知見、定例MTGの議事録などをQiita:Teamの記事に溜めてきました。記事には必ずタグ付けをしておき、関連記事はタグで検索できるようにしていました。しかし、記事が増えていくにつれ、その運用も限界を迎えていました。 記事が増えすぎた結果、タグが形骸化し、キーワード検索をするしかない状況になりました。 慣れている人はいいで
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
背景 APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なREST APIドキュメントを作成する - Qiita これまでずっとREST APIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。 markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
Excel 方眼紙撲滅委員会 活動報告 2012.09 #yapcasia #ltthon
モックアップやプロトタイプづくりを 加速させる。それが SVG。@DIST.4 「Life is Short」
Pandocでテキストファイルからドキュメント生成 - プログラマの思索
以前から、テキストファイルからWord、PDF、epub出力するツールを探していた。 Haskellで作られたツールPandocでようやく意図できたものが出力できたのでメモ。 【元ネタ】 『ソフトウェアの基礎』のePub版を公開しました。 - みずぴー日記 Pandocのリンク: プログラマの思索 Pandoc - Demos 【インストール】 Windowsでは、ワンクリックインストーラーを使えば、HaskellのGHCを入れなくてもツールを導入できる。 Pandoc - Installing pandoc --help で認識すればOK。 Rubyのgem、Pythonのeasy_installに相当するHaskellのライブラリインストールコマンドcabalをインストールするのは面倒だったから。 【epub, word出力方法】 Pandoc - Creating an ebook
人類がプログラミングをやめるまで、フルスクラッチの仕事は残る
プログラムレス開発が主流の今、プラムザはあえて「フルスクラッチ専門で開発する」と宣言する。同社の代表取締役 島田徹氏と取締役 内藤洋史氏はそれぞれ、フルスクラッチ開発のメリットを語る。その内容は、以下のようなものだった。 後編では、引き続き「なぜ今、あえてフルスクラッチ開発なのか」を掘り下げていく。 要件定義は方法そのものではなく、コミュニケーション技術で決まる ――フルスクラッチ開発では、要件定義が大変なんじゃないでしょうか？ 島田氏 必ずしもそうとはいい切れません。そもそも、要件定義の時点では、お客さんの要望そのものが固まっていないことが多いです。なので、まずは直感的に分かりやすい「画面」を使って話をするのが、要件定義の常とう手段です。OSツールを使えば、その場で画面が作れるので、確かに画面の要件を決めるのは楽だと思います。 しかし、OSツールだと、まずは「できる・できない」という判断
YARD - A Ruby Documentation Tool
What Is YARD? YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions. Above is a highlight of the some of YARD's notable features. And of course YARD comes with muc
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
目的に沿ったDocumentation as Codeをいかにして実現していくか / PHPerKaigi 2021
Excel 方眼紙撲滅委員会 活動報告 2012.11 #odstudy