網羅的なPRDやDesign Docを書かなくなった - kosui
2024/06/12 16:16 結論を追記 2024/06/12 20:29 より記事の内容を分かりやすく理解頂くため、タイトルを「PRDやDesign Docを書かなくなった」から変更 2024/06/13 20:39 結論にフロー情報・ストック情報に関する意見を追記 結論 この記事では、「様々な観点を考慮して網羅的にドキュメントを書いて、それを関係者にレビューしてもらう」のではなく、関係者と同期的に対話しながら、観点や選択肢やそのトレードオフを洗い出すことで、少ない手数でより良い答えが見つけられると主張する。 ただし、対話のために必要なドキュメントは事前に書いておくべきだし、対話した結果はドキュメントに残すことが望ましい。そして、そのドキュメントのフォーマットはPRDやDesign Doc以外でも良い。例えば、ADRはアーキテクチャに関する議論の過程と結果を述べる上で必要十分なフォー
ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
Deno 1.38: HTML doc generator and HMR
The Deno ecosystem continues to mature, and with the 1.38 release, we’re excited to introduce significant improvements to the deno doc command. Topping the list is the ability to produce static site documentation using the new deno doc --html feature, a game-changer for developers looking to share and publish their project documentation. If you already have Deno installed, upgrade to version 1.38
プログラマーに贈る、わかりやすい文章を書くための技法 - LIVESENSE ENGINEER BLOG
これは Livesense Advent Calendar 2022 DAY 8 の記事です。 転職ドラフトでエンジニアをしている verdy_266 です。 僕の2022年を振り返ると、採用広報チームでの活動を無視することはできません。転職ドラフトの開発を行う傍ら、昨年末に採用広報チームにジョインし、記事の執筆や校正に多くの時間を割いてきました。 今まで記事を投稿したことがなかったこちらのブログにも共作含め5記事を投稿し、11月には Software Design への寄稿の機会をいただくこともできました。文章を書くことが思った以上に好きなんだなと発見があった年でもありました。 made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp 弊
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
Announcing Docusaurus 2.0 | Docusaurus
Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️ At Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content. After 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. From now on, we now plan to respect Semantic V
Diagram as Code
Diagram as Code6 different ways to turn code into beautiful architecture diagrams
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
Notionでのドキュメント管理の何がつらいか - パルカワ2
Notionでドキュメントを書いてる。ドキュメントは書く、共有する、読むなどユーザーそれぞれ色々なシナリオがあり、そのシナリオそれぞれでつらみがある。 Notionに限らずすべてのサービスは使っていればつらいところはあると思っていて、つらいとはいえNotionから別のドキュメント管理サービスに乗り換えたいという気持ちは全くなく何がつらいのか考えNotionでなにか出来ることはないか考えたり、つらみを共有することで知見を得たい。 検索がつらい フロー型とストック型の情報が入り乱れる 検索をする時はストック型の情報を探すことが多い。例えば、リリース作業手順ドキュメントを探したいときに「リリース 作業 手順」で検索するけど日報や議事録などは検索から除外したい。 Notionの検索には、FilterでPageの指定が出来るのでそれを駆使するしかない。Pageの指定をした場合、Pageの配下は検索対
社内のドキュメンテーションの取り組みと、Kitenのご紹介 - Pepabo Tech Portal
はじめに 技術部の @june29 と申します。最近の趣味は「お散歩」で、よく晴れた休日には妻といっしょに2時間くらい歩き回ったりしています。この記事では、わたしが2020年から力を入れて取り組んでいる社内におけるドキュメンテーションの活動の一部を紹介したいと思います。 問題意識 もともと、ペパボで働く人々には「書く」という行為が定着しています。現在利用中のサービスを見渡してみると、GitHub、Slack、Google Docs、Scrapbox、Notionなどがあり、常に積極的な読み書きが行われています。 しかし、ドキュメンテーションという観点から見て、すべてが理想的にうまくいっているとは言えない状況であるとも思っていました。具体的には、下記のような課題があると感じていました。 書く場所が何種類もあり、どこになにが書かれているかがわかりにくい 場所ごとにアクセス制限が行われており、ど
Announcing the New TypeScript Handbook - TypeScript
Hey folks, we’re happy to announce that a fresh re-write of the TypeScript Handbook is out of beta and is now our website’s primary resource for learning TypeScript! Read the handbook on Web / Epub / PDF In the last year, the TypeScript team has heavily focused on ramping up the scale, modernity and scope of our documentation. One of the most critical sections of our documentation is the handbook,
MkDocs
MkDocs Project documentation with Markdown. MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial, then check the User Guide for more information.
ミーティングログ/議事録の取り方についてのメモ
この記事はミーティングログの取り方についてのメモです。 以前書いた勉強会でのメモの取り方と似た話です。 勉強会でのメモの取り方について | Web Scratch 自分は書きながら話を聞くのが習慣化しているので、こんな感じでミーティングログ(ミーティングノート)を書いていますという話です。 この記事はメモ書きなのであんまり読みやすくないです。 このログの取り方は正確さログや整形されたログを取る方法ではありません。 2種類のミーティングログ 自分の場合は主に2種類のミーティングログを取ることが多いです。 ミーティングの内容によってどちらで取るのかを使い分けています。 リアルタイムモード 対面、リモートでのミーティング 回想モード ブレスト系のミーティング(JavaScript Primerの出版に関するミーティングなど) この記事ではこの２つのミーティングログの取り方について書いていきます。
Markdown と GitHub で社内規程を便利に管理 - クックパッド開発者ブログ
VP of Technology の星 (@kani_b) です。技術基盤や研究開発領域などを担当しつつ、社内の色々なことを技術の力でいい感じにする仕事をしています。セキュリティや AWS の話が好きです。 さて、みなさんは、ご自身が勤務する会社の就業規則を読んだことはあるでしょうか。 エンジニアに限らず、会社の全スタッフが仕事をする上で関わってくるのが、就業規則や情報セキュリティドキュメントなど、会社のルールや規程を記す文書です。 特にセキュリティやインフラに携わるエンジニアは、その改訂も含め携わったことがある方もいるのではと思います。 よくある文書管理 こうした文書は、以下のように管理されていることが多いようです。 ベースドキュメントは Word 保存時は PDF で保存 版管理は Word の編集履歴 + PDF に保存する際のファイル名 編集は担当部門, 担当者のみが行う かつての
Build optimized websites quickly, focus on your content | Docusaurus
Build optimized websites quickly, focus on your content Powered by MDXSave time and focus on text documents. Simply write docs and blog posts with MDX, and Docusaurus builds them into static HTML files ready to be served. You can even embed React components in your Markdown thanks to MDX. Built Using ReactExtend and customize your project's layout by writing React components. Leverage the pluggabl
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024
Typst: Compose papers faster
テクニカルライティングの基本 2023年版
IT英語スタイルガイド | IT英語スタイルガイド
GitHub - google/eng-practices: Google's Engineering Practices documentation
