サクサク読めて、
アプリ限定の機能も多数！
アプリで開く
カケハシのプラットフォームチームでソフトウェアエンジニアをしているすてにゃん (id:stefafafan) です。今回はチームに配属されて数ヶ月の私が、いかにして社内ドキュメンテーションの階層構造を整理し、情報の検索性を向上させたかについてお話します。 はじめに この記事の想定読者 課題意識 メンバーへの共有と相談 社外事例の調査 esa の階層整理 第 1・第 2 階層の整理 ストック情報とフロー情報を意識した階層の整理 esa の機能をフル活用する 効果や今後について はじめに カケハシでは全社的にドキュメンテーションツールとして esa - 自律的なチームのための情報共有サービス を利用しています。それぞれのチームやプロダクトごとに階層を切ってドキュメントを書いています。 プラットフォームチームでは認証基盤などの社内プラットフォームシステムを開発しているため、自チームが運用する各種
アーカイブでは視聴者からのQ&Aを見ることができます ドキュメント文化を浸透させる方法 おすすめのドキュメント管理ツール ドキュメントがない状態での引き継ぎ 運用しやすいドキュメント構造とは 増えすぎたドキュメントの管理方法 ドキュメントを残さないシニアエンジニアへの対策 ドキュメントへの苦手意識を克服する方法 誰もドキュメントを読んでくれません 複数人でドキュメント管理するコツ本記事のTopics 書籍の概要・構成 おすすめの書籍 読み手の理解 ドラフトの執筆 フィードバックの収集と組み込み ドキュメントの品質測定 日本語を学べる書籍 ドキュメントは開発側の生産性とユーザーの利便性を高めるもの。ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。本書は、経験に長けた執筆者たちがドキュメ
本記事はFigma Advent Calendar2022 16日目の投稿です。 仕様書を作るとき、あの情報はこのツールで書いたほうが楽、みたいな感じで、あっちこっちに情報が散逸することがありますよね。 かくいう私も、事業会社でデザイナーとPMの狭間みたいな仕事をしていまして、UMLだのデザインだの、複数のツールを跨いで作業をすることが多かったのですが、最近は安定してFigma＋Notionで作業をしています。 これはデザイナーなのでFigmaの使い方に慣れている、ということもあるんですが、Figmaの自由度の高さや、Notionの情報統合性の高さ（この辺は後述します）が筆者の仕事範囲と大変に相性が良く、今の所ここがベストという形に落ち着いているので、軽く紹介してみようと筆を取りました。ご興味があれば読んでください。 TL;DR（この記事のあらすじ）エンジニア・非エンジニア・社内外い
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](/image.pl?url=https%3a%2f%2fcdn-ak-scissors.b.st-hatena.com%2fimage%2fsquare%2f92dc44fc8a8e7426db0092ff0228703157a1c539%2fheight%3d288%3bversion%3d1%3bwidth%3d512%2fhttps%253A%252F%252Fqiita-user-contents.imgix.net%252Fhttps%25253A%25252F%25252Fqiita-user-contents.imgix.net%25252Fhttps%2525253A%2525252F%2525252Fcdn.qiita.com%2525252Fassets%2525252Fpublic%2525252Farticle-ogp-background-afbab5eb44e0b055cce1258705637a91.png%25253Fixlib%25253Drb-4.0.0%252526w%25253D1200%252526blend64%25253DaHR0cHM6Ly9xaWl0YS11c2VyLXByb2ZpbGUtaW1hZ2VzLmltZ2l4Lm5ldC9odHRwcyUzQSUyRiUyRnMzLWFwLW5vcnRoZWFzdC0xLmFtYXpvbmF3cy5jb20lMkZxaWl0YS1pbWFnZS1zdG9yZSUyRjAlMkYyNDE5MDklMkY1ZGU1MmRjNTAzODc4N2IzNWZjOTJkODhiNDY4ZmM3YTI2OTM2NjI1JTJGeF9sYXJnZS5wbmclM0YxNjY0NzYzNzQ4P2l4bGliPXJiLTQuMC4wJmFyPTElM0ExJmZpdD1jcm9wJm1hc2s9ZWxsaXBzZSZiZz1GRkZGRkYmZm09cG5nMzImcz0wMWQ5N2I2MTkzM2RhYmMxODNkOGRlYmI3ZmFiOTBkYQ%252526blend-x%25253D120%252526blend-y%25253D467%252526blend-w%25253D82%252526blend-h%25253D82%252526blend-mode%25253Dnormal%252526s%25253De63cbc0e90588ee773256464ed72cf53%253Fixlib%253Drb-4.0.0%2526w%253D1200%2526fm%253Djpg%2526mark64%253DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk2MCZoPTMyNCZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMxRTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LXBhZD0wJnM9NzE1Zjc2MTRjYTk2OWVlNzc2NmYxOTk5OTQzYjQzNjc%2526mark-x%253D120%2526mark-y%253D112%2526blend64%253DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTgzOCZoPTU4JnR4dD0lNDBzeWFudGllbiZ0eHQtY29sb3I9JTIzMUUyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1wYWQ9MCZzPTMxZDY5NThkZmJiYTlkYzBlZGMxNjBjN2I2ZTY5Mzg0%2526blend-x%253D242%2526blend-y%253D480%2526blend-w%253D838%2526blend-h%253D46%2526blend-fit%253Dcrop%2526blend-crop%253Dleft%25252Cbottom%2526blend-mode%253Dnormal%2526s%253Dbea8cd64dcc9f57665930f9e48a48e89&f=jpg&w=240)
文書を記述する際に、構造――ここでは見出しなどを指す――を機械が可読な形で行うことに意味はあるだろうか。 前回の続きといえば続き。 squeuei.hatenablog.com 前提scrapbox.io 使わない文書構造の宣言に意味があるのか？ 「文字が大きくなって格好いい」以上の意味がない 使わないのにせっせと構造を宣言しているの、マジで意味わからんmarkdownはとにかくデカイ文字が簡単に書ける事が便利なだけなのでは？ 宣言した文書構造を有意義に使う方法がスクリーンリーダーと索引生成以外に何かあれば教えて欲しい #で<h1>や<h2>になる文書構造化がしたいと言いつつ、実はデカイ文字を書きたいだけ 反論markdownが万能でも素晴らしい完全無欠のものでもないというのは理解する。 が、しかし、文字が大きいことと、構造上の意味を持つこととは違う。今価値がないからと言って、将来に
こんにちは、今回はデータ基盤構築を担当しているmarushoがお送りします。 今日はestieで実践しているデータベースのドキュメント管理方法をご紹介します。 はじめに 独自成長していくデータベースたち 失われたドキュメント どうすれば低コストなドキュメント管理ができるのか そして生まれた、schema collectorという自動化ツール SchemaSpyMysql diff Priv Page ECS タスクスケジューラ ドキュメントを腐らせない おわりに はじめに estieはオフィスを中心とした不動産データを取り扱うスタートアップ企業です。 estie（オフィス探しサービス）とestie pro（不動産事業者向けデータプラットフォーム）の2つのサービスを運営しています。 詳しくは、こちらの記事をご覧ください。 inside.estie.co.jp estieでは、不動産に関する
ここ最近tblsのアップデートエントリを書いていなかったのですが、最近変更をいくつか行いました。 このまま放置するとちょっと紹介しきれなくなりそうなので、ここら辺で放出しておこうと思います。 紹介時点のtblsのバージョンはv1.29.0です。 PostgreSQLでの public. スキーマ表示仕様変更 tblsでは、もともとPostgreSQLの public. スキーマ（ schema_name.table_name.column_name の schema_name ）だけ特別に非表示にしていました。 こうなっていた理由は、私がPostgreSQLでのスキーマを意識した運用経験がなかったことに寄る部分が大きいです。「デフォルトだから非表示で良いだろう」と。 ところで、tblsにはlintの機能があります。「テーブルカラムにコメントが書かれているか？」とか「外部キーの参照元にIND
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
UMLをテキストベースで記述できるPlantUMLを使っている方は多いのではないでしょうか。クラス図を流用する形でER図も描くことができます。そして、データベースはすでにあり、そこからPlantUML用に出力できればいいのに、と考えている方もまた多いでしょう。 そんな方にお勧めなのがplant_erdです。各種データベースに対応したER図エクスポートソフトウェアです。 plant_erdの使い方 出力した内容をPlantUMLで表示しています。 plant_erdはSQLite3、MySQLそしてPostgreSQLに対応しています。各データベースの内容をそのままPlantUML向けに出力が可能です。特定のテーブルだけを出力対象にもできます。リレーションも再現され、データベース構造をドキュメントに書き出すのにぴったりです。 plant_erdはGo製のオープンソース・ソフトウェア（MIT
よく知られているように、ドキュメントには「構造」があります。 WebページではHTMLとCSSにより構造とスタイルを分離するべきとか、Wordでは書式設定をスタイルとして定義して使うことで構造とスタイルを分離するべきとか、ドキュメントの「べき」論で必ず言及される「構造とスタイルの分離」における「構造」です。 昨日までの話ではPDFにもドキュメント構造というのが出てきました。あれは、この「構造とスタイルの分離」というときの「構造」とは別物なので注意してください。 たぶん、PDFのドキュメント構造には、「ドキュメントを表すデータ構造」くらいの意味合いくらいしかありません。 一方、ドキュメントの話において「構造とスタイルの分離」というときの「構造」は、もうちょっとこうなんていうか、セマンティックな話です。 データをどう構成するかではなく、ドキュメントで表したい意味をどう構成するか、という話。 し
Webエンジニアの横塚です。 皆さんは情報共有ツールは利用しているでしょうか。 LCLエンジニアチームでは先日、以前から利用していたQiita:Teamからesa.ioに移行することにしました。 移行の背景と、実際に移行してみてどうだったかを簡単に紹介したいと思います。 teams.qiita.com docs.esa.io 移行しようと思った理由 Qiita:Teamは本来やりたかったwiki的な使い方にあまり合ってなかった LCLでは、システム仕様や、共有しておきたい知見、定例MTGの議事録などをQiita:Teamの記事に溜めてきました。記事には必ずタグ付けをしておき、関連記事はタグで検索できるようにしていました。しかし、記事が増えていくにつれ、その運用も限界を迎えていました。 記事が増えすぎた結果、タグが形骸化し、キーワード検索をするしかない状況になりました。 慣れている人はいいで
背景APIドキュメントを書くのが楽になるツールまとめ - Qiita iodocsで便利なRESTAPIドキュメントを作成する - Qiita これまでずっとRESTAPIドキュメントをwiki上で管理していて、重たいページ上で特殊記法使ったり、スタイルの調整に時間を取られるのが辛かった。そこで良さげなドキュメントツールを色々調べてたんだけど、最終的にapiary.ioが一番良さそうという結論になってきた。 このサービスの主な特徴。markdown記法でAPIドキュメントを記述できる ドキュメントの生成と同時にAPIのモックサーバを用意してくれる サインアップから5分くらいあればドキュメント公開できる。ドキュメントのホスト先を気にしなくてもいい。 特にドキュメントと一緒にモックを作ってくれるのは他にはないポイントでかなり便利。 使ってみる サインアップはGithubアカウントで h
モックアップやプロトタイプづくりを 加速させる。それがSVG。@DIST.4 「Life is Short」
以前から、テキストファイルから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ツールだと、まずは「できる・できない」という判断
What Is YARD? YARD is a documentation generation tool for theRubyprogramming 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 customRuby 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ページを開く
