「プロダクトとしてのドキュメント」を目指してドキュメンテーションへの考え方をアンラーンする - エス・エム・エス エンジニア テックブログ
この記事は、「株式会社エス・エム・エス Advent Calendar 2023」3日目の記事です。 qiita.com 介護事業者向け経営支援サービス「カイポケ」の開発をしている @koma_koma_d です。 私が所属しているチームは、介護事業所の業務のなかの一部の領域を扱う箇所の開発を担当しています。最近、このチームの置かれている状況に変化があり、それに伴って（他にも様々な変化が必要になっているのですが）ドキュメンテーションについての方針転換がありました。この方針転換は、私個人にとってもこれまでの働き方を一部改めるきっかけになるものでしたので、今回の記事では、その方針転換について紹介したいと思います。 これまでのチームの状況 私たちのチームが担当している領域のシステムは、大雑把にいうと、ユーザーが触るアプリケーション（サーバーサイドレンダリングをベースとする典型的なWebアプリケー
tblsを導入してDBドキュメントを継続的にメンテナンスする - Pepabo Tech Portal
EC事業部でシニアエンジニアリングリードをしているkenchanです。この記事はEC事業部ブログリレーの4日目の記事で、3日目はakatsuuraによるRuby のコードリーディング会に参加して1年経ちましたでした。 カラーミーショップの開発チームでは、2020年末にデータベースドキュメンテーションツールとしてtblsを導入しました。本記事では、tblsの機能や導入の狙いから、実際の移行のプロセスをふりかえり、最後に今後やっていきたいことについて紹介します。データベースドキュメントの継続的なメンテナンスに課題を感じている方の参考になれば幸いです。 tblsとは何か k1LoW/tblsは、ホスティング事業部の@k1LoWが開発、メンテナンスをしているデータベースのドキュメンテーションツールです。tblsを使うことで、MySQLやPostgreSQLなどのRDBMSはもちろん、BigQuer
プロダクト開発でドキュメントを書かないとどうなるか
Agile Manifestoには以下のように書いてあります。 動作するソフトウエアは包括的なドキュメントにまさる ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよ
「書く」のは特別な道具 - naoyaのはてなダイアリー
This is why you shouldn't interrupt a programmer (なぜプログラマの作業に割り込むべきではないか) という4コマ漫画が話題になっていた。これは別にプログラマではなくても「わかるわかる」という感じの話。 コメントを見ると、だから作業を中断してもすぐ再開できるように自分の考えることをなるべく書き出すようにしているという人が結構多かった。なるほど。 今日は雨が降ったせいで予定が一つキャンセルになったことだし、ちょうどいい機会なので、文章で何かを書くということについて自分が思っていることを書いてみようとおもう。以前 Software Design のドキュメントの書き方特集みたいな号に似たような趣旨の話を寄稿したのだけど、「書く」というのは単に物事を忘れないようにするための行為に留まるものではなくて、自分の考えを整理するための道具なのだ、ということが
【翻訳】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分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
ドキュメントが更新されない問題 - Konifar's ZATSU
むかし、この国が深い森におおわれ、そこに太古からの神々がすんでいた頃から語り尽くされているドキュメントが更新されない問題について雑に書く。 実態が変わったのにドキュメントが更新されない問題はいつどの時代も絶えない。これにいちいち憤りを感じるのは不幸になるだけなので、何かしら対処を考えておかねばならない。パッと思いつくのは次のようなものだろうか。 使う 使わないから更新もされなくなる。定期的に使われるように設計して、そもそも使わない場合は消した方がいい いっそ参照回数が少ないドキュメントは自動でアーカイブしちゃうみたいな硬派なスタイルの方がいいのかも 詳細に書きすぎない 細かいところを書きすぎると保守できない。骨組みだけ大事にして、細かいところはフロー情報として分けて書くのがよい 管理者を置く ちゃんと更新されるようロールを作る。属人化しないようにロールを引き継ぐ設計も必要 個人的にはあんま
形式手法とテスト、そして、その先について
ライフロボティクス株式会社 川口 順央 形式手法とテスト そして、その先について 1 自己紹介 2 はじめに 2004年から形式手法に興味を持ち、勉強と試行の繰り返し 個人レベルでは何度か現場に導入したことあり（Spin, Alloy, CSP など） 川口 順央（かわぐち まさてる） @masateruk ライフロボティクス株式会社 CORO開発プロジェクト プロジェクトリーダー http://www.itmedia.co.jp/business/articles/1608/24/news004.html 発表の構成 3 形式手法 形式手法とは 形式的仕様記述とは 形式手法 仕様書作成 テスト計画と実施 導入結果 形式的仕様記述の 導入事例 仕様書の変化 テストの変化 導入から習慣へ 形式的仕様記述の先へ 未来 発表の構成 4 形式手法 ー 形式手法とは 形式手法とは 形式的仕様記述とは
ビジネスに役立つ上手な文章の書き方11のコツ | knowledge / baigie
ベイジの五ノ井です。役職はディレクターですが、編集者の経験があることから、コンテンツや文章のクオリティを管理する立場で働いています。6月からは、ベイジの日報の編集長も務めています。 そんな私の第一回目の記事は、文章について。 デジタル化が進む今、文章力は社会人の最重要スキルといって過言ではありません。 今は会話や電話のような音声コミュニケーションの機会がどんどん減り、多くがメールやチャットのようなテキストコミュニケーションに置き換えられています。文章力がある人には、企画書、社内資料、記事、SNSなど、様々な媒体を通じて自分のメッセージを届け、影響力を高めるチャンスが転がってきます。 これほど重要な文章力について、ほとんどの人は高校以降は専門的な教育を受けることもなく、働き始めます。文章に苦手意識を持っている社会人も非常に多いですが、作家やライターではない社会人が覚えるべき文章のセオリーは僅
社員用に作った文書校正ツールを一般公開した - gecko655のブログ
スクリーンショット これはなに 会社で「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 を参考に、アプリケーションをセキュ
”組織で使える知識”を創る、技術相談の「ナレッジマネジメント」実践 - LIFULL Creators Blog
テクノロジー本部の鈴木(@szk3)です。ソリューションアーキテクト・クラウドアーキテクトとして業務にあたっており、最近はWebRTC周りに興味関心があります。 自分が所属するチームでは「アーキテクト相談」 という技術相談の取り組みを行っています。 今回は、その技術相談で取り入れている 「ナレッジマネメント」および、知識経営の提唱者である野中郁次郎先生が提唱した「SECIモデル」について紹介します。 背景 相談手法 ナレッジマネジメントとは？ SECIモデルとは？ アーキテクト相談の対応範囲 プロセスをスムーズに回せるような環境・運用整備 表面化・連結化における、形式化（ナレッジ化） 運用への向き合い方 回答に時間がかかりませんか？ 他の技術相談窓口と競合しませんか？ ナレッジの効果測定はどうやっていますか？ 情報鮮度への対応はどうしてますか？ まとめ 背景 LIFULLでは、多種多様なプ
実践テクニカルライティング - 開発者が「外国語」を使うときの言語技術達3つ - Qiita
言語技術 というものをご存知でしょうか。 言語技術とは、思考を論理的に組み立て、相手が理解できる様に分かりやすく表現すること。 人前で話す能力や議論の能力、文章を書く能力や論文を書く能力はトレーニングによって身につけられる。我々開発者にとっても、普段の語彙に距離のある相手、たとえば非技術者との会話の際にこの言語技術を意識することがキーになる。記事のタイトルは「外国語」と書いたが、英語は勿論、開発者にとって顧客や非技術者は時として「外国人」。開発者にとって、例えば 英語学習 テクニカルサポートのやり取り の時等に使える、情報を整理する言語技術とツールについて、3つのトピックからまとめた。 『外国語を身につけるための日本語レッスン』に学ぶ、言語技術 『情報を整理するたった5つの方法 LATCH』 Google Sheets 等で、「外国語」を使う相手と状況共有をうまくする仕掛け 1. 『外国語
アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ - Qiita
5月のThoughtWorksのTechnology RadarでもADOPTされたADRという手法について、面白かったので、ざっくり自分なりに調べたメモです。 Technology Radarでは以下のように述べられています。 多くのドキュメントは、読みやすいコードとテストに置き換えることができます。しかし、進化的アーキテクチャでは、将来のチームメンバーの利益と外部の監督のために、特定の設計上の決定を記録することが重要です。Lightweight Architecture Decision Recordsは、重要なアーキテクチャー決定を、そのコンテキストおよび結果と共に取り込むための技法です。これらの詳細は、WikiやWebサイトではなくソース管理に格納することをお勧めします。そうすれば、コードと同期したままのレコードを提供できるからです。ほとんどのプロジェクトでは、この手法を使いたくな
変化に耐え得る esa のカテゴリ設計を徹底的に考えてみた - Feedforce Developer Blog
こんにちは id:masutaka26 です。夜の散歩（意味深）に勤しむ毎日です。 フィードフォースではドキュメント共有ツールには esa と Google ドキュメント1を、コミュニケーションツールには Slack を採用しています。 情報共有はかなり活発で、2021/2/1 現在の esa 記事数は 81,324 です2。 現在のカテゴリ構成と課題 チームのスピードを上げるための大原則 チームのスピードを上げるための情報整理 1. Flow 型と Stock 型の記事を理解する 2. 基本は Flow 型の記事にする 3. 議事録カテゴリは出来るだけ作らない 4. Slack に流れていく情報も Flow 型の記事にする 5. 使い続けられる情報を Stock 記事として引き上げる 6. 整理を頑張らないことで整理の難易度が低くなった 7. esa を全ての情報の起点にする それをチー
マネジメント業を通じて考えた、プロジェクト全体像の認識齟齬を防ぐ誤解されないドキュメント作成術 - ANDPAD Tech Blog
アンドパッドの土方です。 本ブログではEMインタビューで取り上げておりますが、記事投稿は初めてです。 エンジニアマネージャーとしてのイベント登壇や、プロジェクト推進における案件の取りまとめ業務が増えてきており、それに伴ってドキュメントを作成する機会も増えてきました。 自分の考えを整理するとともに、アンドパッドのエンジニアにはこんなこと考えている人もいるよ、的な意味で紹介したいと思います。 何かの参考になれば幸いです。 結論！ 次項からは文字ばっかりで語っているだけになりますので先に結論を書きます。 断面を作るための切り方を意識する 網羅性、単一性を守る 二軸で表現する この三項を守ることで、理解されやすく誤解を招かないドキュメントの完成に近づけると考えています。 ではここからだらだら語ります。 ドキュメントの目的は？ そもそもドキュメントはなんのために作るものでしょうか。 私は、「認識を合
ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
GitHubのREADMEをサクッと高品質で書けるサービス作ってみました。 - Qiita
みなさんは GitHub でオープソースソフトウェア(OSS)を開発して公開する時、README をどのように書いているでしょうか？ GitHub が自動で作ってくれる README に含まれるのはタイトルだけですし、OSS 開発初心者の場合、そもそも README に何を含めるべきかわからないという方もいらっしゃるのではないでしょうか？OSS 開発に慣れている方でも、コードを書くのはいいけれど README を書くのは面倒だと思ったことはありませんか？今回はそんな README 難民の方々向けの Web サービスを作ってみました。 LEADYOU - README Generator Web サイトへ 使い方 使い方は簡単です。トップページで GitHub の Public リポジトリの URL を入力してNext Stepボタンを押すと、README に書くべき内容ごとにフィールドが設
「人は記事をちゃんと読まない」からはじまる意識改革｜平野太一
仕事柄、日々投稿されるたくさんの記事を読みます。あたらしい視点をもらえる記事に出合えるとうれしくなる一方、もっとこうしたらいいのにな…と思ってしまうものもあります。 後者で感じるのは、書き手と読み手の「読む」に対する温度差を意識できていないことです。 基本的に、書き手は「記事を全部読んでもらえる」と思っているのに対して、読み手は「興味をひくものがあれば読む」というスタンス。興味をひかれなければ読まないと判断します。そこで大事なのが、読んでもらうための努力。それをしていない人が多いと思うのです。 そこで今回提案したいのが、「人は記事を全部読んでくれる」のではなく、「人は記事をちゃんと読まない」から、「じゃあどうする？」と考える意識改革です。 自分の記事は「読んでくれる」と思いがち読み手と書き手の温度差を自覚したのは、Takram 田川さんのインタビュー記事です。記事の一節に、衝撃を受けました
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ドキュメント・コミュニケーションを本気で狙う - inteltank
https://twitter.com/MinoDriven/status/1584050332765519872
ヒヤリハット報告書の書き方。簡単に分かりやすく書くコツ